В Яндексе пишут разную документацию, используя множество инструментов. Я заострю внимание на Помощи (документах для пользователей), т.к. занимаюсь непосредственно ей.
Начнем с того, какие этапы проходит документация в Яндексе, а затем рассмотрим инструменты, используемые на каждом из них.
- Готовим план и структуру документа, пишем текст. В нужных местах добавляем иллюстрации, ведь часто одна картинка понятнее тысячи слов.
- 2. Локализация.
- Документ с картинками готов на русском языке — переводим его, чтобы он был доступен и для пользователей в других странах
- 3. Публикация.
- Документ переведен на все нужные языки — показываем его пользователям.
- Пишем текст
- Техписатели в Яндексе используют логическую разметку документа и формат DITA XML — чем это удобно?
- это обеспечивает единый источник данных, из которого мы можем получить документы в разных форматах — HTML, PDF, EPUB;
- это позволяет редактировать содержимое и внешний вид по отдельности: например, при изменении дизайна не придется менять контент.
Для работы с DITA XML мы используем редактор Syntext Serna, допиленный нашими разработчиками.
Готовим картинки
Иллюстрации можно разделить на 3 вида:
- схемы (MS Visio для Windows; DIA для Windows, Mac OS и Linux);
- cкриншоты (Jing, Snagit для Windows и Mac OS; GIMP, DIA для Linux);
- интерактивные скриншоты, в Яндексе мы называем их «живыми картинками» (Handy Image Mapper) — пример использования в
Помощи браузера Yandex. - Иногда снять хороший скриншот сразу нельзя — например, если данные секретны; если в тестовом интерфейсе опечатки, а скриншоты нужны уже сейчас. Как поменять любой текст на веб-странице, вы можете прочитать в посте Алексея «Нельзя просто так взять и снять скриншот браузера».
Локализация
Локализация подразумевает перевод документа на нужные языки для определенных доменов. Как это всё происходит?
- Размечаем исходный документ — об этом упоминала Елена в посте «Особенности создания веб-документации для пользователей».
- Конвертируем DITA XML в формат XLIFF — для того, чтобы получить из разметки исходника файл для перевода. Раньше это вручную выполнял переводчик, сейчас у нас для этого есть свой конвертер.
- Переводим сегменты файла XLIFF в САТ-системе SwordFish.
- Конвертируем XLIFF обратно в DITA XML.
Публикация
Чтобы посмотреть документацию в верстке, «собираем» ее из исходников с помощью скрипта. Это делается для того, чтобы проверять промежуточные версии при разработке и чтобы показывать готовый документ пользователю.
Собранный в верстке контент помещается в дебиановские пакеты, которые устанавливаются на продакшн-серверы.
Сборка контента и пакетов выполняется на *nix-серверах. Для доступа к ним техписатели на Windows используют Putty или WinSCP, а маководы и линуксоиды справляются с командной строкой.
Собранный в верстке контент помещается в дебиановские пакеты, которые устанавливаются на продакшн-серверы.
Сборка контента и пакетов выполняется на *nix-серверах. Для доступа к ним техписатели на Windows используют Putty или WinSCP, а маководы и линуксоиды справляются с командной строкой.
Подведем итоги:
- пишем документы в редакторе Serna (формат DITA XML);
- схемы пилим в Visio и DIA;
- скриншоты снимаем с помощью наборов Jing + SnagIt или GIMP + DIA;
- получаем координаты для интерактивных скриншотов — Handy Image Mapper;
- переводим тексты в CAT-системе SwordFish;
- собираем документацию на *nix-серверах через Putty, WinSCP или командную строку.
Всю разрабатываемую документацию нужно где-то хранить и учитывать процессы работы с ней. О том, как организовано хранение и учет документов, я расскажу вам в следующем посте.