В докладе речь пойдет об инструментах документирования в Яндексе. Екатерина рассмотрит этапы подготовки пользовательской документации и расскажет, какие инструменты используются на каждом этапе.

1. 1

2. 2
Инструменты для подготовки
пользовательской документации
Куненко Екатерина
разработчик пользовательской документации
TFR, Гипéрбатон, Екатеринбург, 26 сентября 2014

3. 3
Обо мне
в Яндексе — чуть больше 1 года
разработчик пользовательской
документации
пишу Помощь для
Яндекс.Почты, Яндекс.Диска и
других сервисов

4. 4
О чем поговорим
Этапы работы с документацией в Яндексе
Инструменты разработки и локализации документации
Некоторые практики применения инструментов

5. 5
Этапы
документирования
Процессы, задействованные в подготовке
документации

6. 6
Хранение
Процессы
Разработка
текст + иллюстрации
Локализация Публикация

7. 7
Орудия производства
Инструменты разработки и локализации
документации в ЯндексеОрудия производства

8. 8

9. 9
Логическая разметка (DITA XML)
HTML
PDF
EPUB
…

10. 10
Логическая разметка (DITA XML)
Документ
Контент
Внешний
вид

11. 11
Логическая разметка (DITA XML)
Документ
Icons: Double-J Design

12. 12
Syntext Serna

13. 13
Иллюстрации
Схемы
Скриншоты
Живые картинки

14. 14
Схемы
MS Visio – коммерческий продукт
Dia – кроссплатформенный бесплатный
редактор диаграмм

15. 15
Скриншоты
Jing и Snagit
GIMP и Dia

16. 16
Живые картинки

17. 17
Живые картинки — как?
1. Разметка областей на скриншоте

18. 18
Живые картинки — как?
2. Получение координат
» Handy Image Mapper

19. 19
Живые картинки — как?
3. Связь координат и ссылок в коде XML
<imagemap>
<image href="image/stat-letter-overview.png"/>
<area>
<shape>rect</shape>
<coords>461,14,622,49</coords>
<xref href="stat-letter/prompt.xml"/>
</area>
</imagemap>

20. 20
Как сделать хороший скриншот
поиск
данных
тестовые
аккаунты
графический
редактор
долго
затратно
неудобно
подобрать правильные данные

21. 21

22. 22
Отладчики HTML-страниц
в браузерах
инструменты
разработчика (F12)
средства
разработчика (F12)
плагин Firebug

23. 23
Средства документирования
• Формат DITA XML, редактор Syntext SernaПишем
• MS Visio / DiaСхемы
• Jing и Snagit / GIMP и DiaСкриншоты
• инструменты разработчика в браузерах
Yandex, MS IE
• плагин Firebug для Mozilla FF
Хороший
скриншот
• Handy Image MapperЖивые
картинки

24. 24
Локализация
Локализационная разметка
исходных текстов
Формат XLIFF
CAT-система SwordFish
Конвертер DITA-XLIFF

25. 25
Публикация
Что
– сборка документации
– сборка пакетов для выкладки на кластер
Где
– разработческие *nix-серверы документации
Чем
– Putty, WinSCP и др.
– командная строка

26. 26
Хранение

27. 27
Системы контроля версий
• Хранение нескольких версий
документа
• Возможность возвращаться
к предыдущим версиям
• Контроль изменений

28. 28
SVN-клиенты
Subversion command-line и
TortoiseSVN
Command-line SVN

29. 29
Хранение контента
Тип документации (репозиторий)
Ветки репозитория
– разработческая
– стабильная
Языковые каталоги внутри ветки
Документы

30. 30
Структура документа
DITA-топики (тексты)
image – иллюстрации
work – рабочие материалы

31. 31
Хранение
Надежность
Прозрачность
Удобство

32. 32
УчетУчет

33. 33
Как работает?
Документы
Задачи
Люди

34. 34
Сделали так

35. 35
Практические советы

36. 36
Наши находки
Живые картинки
Отладчики HTML-страниц в браузерах
Организация репозитория для хранения документации
Система учета документации в багтрекере

37. 37
Спасибо за
внимание!

38. 38
Куненко Екатерина
разработчик пользовательской
документации
Клуб техписателей clubs.ya.ru/x-plain
yandex-techdoc@yandex-team.ru