Клуб технических писателей

Инструменты для подготовки пользовательской документации

Екатерина
27 марта 2015, 12:51
В Яндексе пишут разную документацию, используя множество инструментов. Я заострю внимание на Помощи (документах для пользователей), т.к. занимаюсь непосредственно ей.
Начнем с того, какие этапы проходит документация в Яндексе, а затем рассмотрим инструменты, используемые на каждом из них. 
  1. Разработка. 
  1. Готовим план и структуру документа, пишем текст. В нужных местах добавляем иллюстрации, ведь часто одна картинка понятнее тысячи слов.
  2.   2. Локализация.
  3. Документ с картинками готов на русском языке — переводим его, чтобы он был доступен и для пользователей в других странах
  4.   3. Публикация.
  5. Документ переведен на все нужные языки — показываем его пользователям.

  6. Пишем текст
  7. Техписатели в Яндексе используют логическую разметку документа и формат 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.
  • Иногда снять хороший скриншот сразу нельзя — например, если данные секретны; если в тестовом интерфейсе опечатки, а скриншоты нужны уже сейчас. Как поменять любой текст на веб-странице, вы можете прочитать в посте Алексея «Нельзя просто так взять и снять скриншот браузера».

Локализация
Локализация подразумевает перевод документа на нужные языки для определенных доменов. Как это всё происходит?
  1. Размечаем исходный документ — об этом упоминала Елена в посте «Особенности создания веб-документации для пользователей».
  2. Конвертируем DITA XML в формат XLIFF — для того, чтобы получить из разметки исходника файл для перевода. Раньше это вручную выполнял переводчик, сейчас у нас для этого есть свой конвертер.
  3. Переводим сегменты файла XLIFF в САТ-системе SwordFish.
  4. Конвертируем XLIFF обратно в DITA XML.

Публикация
Чтобы посмотреть документацию в верстке, «собираем» ее из исходников с помощью скрипта. Это делается для того, чтобы проверять промежуточные версии при разработке и чтобы показывать готовый документ пользователю.
Собранный в верстке контент помещается в дебиановские пакеты, которые устанавливаются на продакшн-серверы.
Сборка контента и пакетов выполняется на *nix-серверах. Для доступа к ним техписатели на Windows используют Putty или WinSCP, а маководы и линуксоиды справляются с командной строкой.

Подведем итоги:
  • пишем документы в редакторе Serna (формат DITA XML);
  • схемы пилим в Visio и DIA;
  • скриншоты снимаем с помощью наборов Jing + SnagIt или GIMP + DIA;
  • получаем координаты для интерактивных скриншотов — Handy Image Mapper;
  • переводим тексты в CAT-системе SwordFish;
  • собираем документацию на *nix-серверах через Putty, WinSCP или командную строку.

Всю разрабатываемую документацию нужно где-то хранить и учитывать процессы работы с ней. О том, как организовано хранение и учет документов, я расскажу вам в следующем посте.
15 комментариев
Подписаться на комментарии к посту
Спасибо. Интересно было узнать о вашем "наборе инструментов".
Правда внешние ссылки несовсем рабочие, т.к. сначала ведут на h.yandex-team.ru и только затем на нужную страницу.
Екатерина
28 марта 2015, 00:01

Спасибо за сигнал! Ссылки поправили.

а в моем случае, так вообще, не рабочие!((((((((((((((((

Екатерина
28 марта 2015, 00:03

Ссылки поправили, спасибо :)

Спасибо!

Интересно, а при локализации Вы используете "разделение" текста разных языков внутри одного топика или под каждый вариант перевода используете отдельный топик?

Например:

Привет

Hi

или

Привет

Hi

Екатерина
28 марта 2015, 00:26

Атрибут locale, отвечающий за локализацию, есть у многих тегов — например

, , . Поэтому отфильтровать для перевода можно отдельный топик, картинку, ссылку и даже просто часть предложения.

Часто описанные Вами два варианта комбинируются, когда, например, топик нужно отфильтровать только для английского и русского языков, а ссылки внутри топика для каждого языка указать свои.

А почему не используете HAT tool, например MadCap Flare? В нем, к примеру, чтобы увидеть как будет выглядеть документ не нужен скрипт - просто переходишь на соседний таб... 

Допускаю, что причина банальна: MadCap Flare не поддерживает *nix системы. Если только под wine.

P.S. Я не отношусь к Яндексу, просто предположил :)

Екатерина
30 марта 2015, 20:13

Комбинация «редактор DITA XML Serna + верстка на сервере» используется писателями Яндекса уже давно. Можно сказать, что так исторически сложилось. 

C одной стороны, нам важно смотреть на результат в той инфраструктуре, которая будет доступна пользователям. А хранить верстку на локальном компьютере и следить, чтобы она постоянно была в актуальном состоянии, — дорого и с точки зрения затрачиваемого времени, и с точки зрения производительности локальных машин.

C другой стороны, мы работаем под разными операционными системами, поэтому нам нужен кросс-платформенный редактор. И желательно, чтобы этот редактор был с открытым исходным кодом, чтобы его можно было адаптировать под наши нужды и задачи. Таким и оказалась Syntext Serna.

С третьей стороны, нашим писателям не составляет труда запускать скрипт на сервере :)

Антонов Игорь
29 марта 2015, 13:42

Большое спасибо! Особенно за Handy Image Mapper

DITA XML используете только для подготовки пользовательской документации? Или например для внутренней технической документации тоже?

Не сталкивалась с таким подходом к оформлению, через XML разметку.

Интересен размах применения и практический опыт.

Екатерина
3 апреля 2015, 16:14

О внутренней технической документации могу сказать только очень поверхностно — не совсем моя область. Да, для ее подготовки мы тоже используем DITA XML, а также разметку Markdown для документов на продукты с открытым исходным кодом (которые публикуются на GitHub).

 

А Вы с помощью чего оформляете документацию?

Давно было сообщение, но вдруг прочтёте =)
Очень интересно, а чем вы пользуетесь для версионирования? Git ли? Если он, то используете какой-нибудь модуль для Review (типа Gerrit'а, Bitbucket'а и подобных)?  

И по-поводу Markdown. А пробовали использовать Markdown как исходник для части текста? В DITA-OT недавно появился плагин, позволяющий это делать. А от наших разработчиков есть желание участвовать в доработке документации на основе Markdown+Git.
migs911,
SVN.


По поводу MD -- часть внешней документации пишется в нем, но это обусловлено "историческими обстоятельствами". Готовить большие объемы текста в MD неудобно, поэтому планов использовать его в качестве исходников для части текста у нас нет.
Юрий,
 понял, спасибо!