Embed Size (px)
DESCRIPTION
В докладе речь пойдет об инструментах документирования в Яндексе. Екатерина рассмотрит этапы подготовки пользовательской документации и расскажет, какие инструменты используются на каждом этапе.
Citation preview
1
2
Инструменты для подготовки
пользовательской документации
Куненко Екатерина
разработчик пользовательской документации
TFR, Гипéрбатон, Екатеринбург, 26 сентября 2014
3
Обо мне
в Яндексе — чуть больше 1 года
разработчик пользовательской
документации
пишу Помощь для
Яндекс.Почты, Яндекс.Диска и
других сервисов
4
О чем поговорим
Этапы работы с документацией в Яндексе
Инструменты разработки и локализации документации
Некоторые практики применения инструментов
5
Этапы
документирования
Процессы, задействованные в подготовке
документации
6
Хранение
Процессы
Разработка текст + иллюстрации
Локализация Публикация
7
Орудия производства
Инструменты разработки и локализации
документации в Яндексе Орудия производства
8
9
Логическая разметка (DITA XML)
HTML
EPUB
…
10
Логическая разметка (DITA XML)
Документ
Контент Внешний
вид
11
Логическая разметка (DITA XML)
Документ
Icons: Double-J Design
13
Иллюстрации
Схемы
Скриншоты
Живые картинки
14
Схемы
MS Visio – коммерческий продукт
Dia – кроссплатформенный бесплатный
редактор диаграмм
15
Скриншоты
Jing и Snagit
GIMP и Dia
17
Живые картинки — как?
1. Разметка областей на скриншоте
18
Живые картинки — как?
2. Получение координат
» Handy Image Mapper
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
Как сделать хороший скриншот
поиск данных
тестовые аккаунты
графический редактор
долго
затратно
неудобно
подобрать правильные данные
21
22
Отладчики HTML-страниц
в браузерах
инструменты разработчика (F12)
средства разработчика (F12)
плагин Firebug
23
Средства документирования
• Формат DITA XML, редактор Syntext Serna Пишем
• MS Visio / Dia Схемы
• Jing и Snagit / GIMP и Dia Скриншоты
• инструменты разработчика в браузерах Yandex, MS IE
• плагин Firebug для Mozilla FF
Хороший скриншот
• Handy Image Mapper Живые
картинки
24
Локализация
Локализационная разметка
исходных текстов
Формат XLIFF
CAT-система SwordFish
Конвертер DITA-XLIFF
25
Публикация
Что
– сборка документации
– сборка пакетов для выкладки на кластер
Где
– разработческие *nix-серверы документации
Чем
– Putty, WinSCP и др.
– командная строка
26
Хранение
27
Системы контроля версий
• Хранение нескольких версий документа
• Возможность возвращаться к предыдущим версиям
• Контроль изменений
28
SVN-клиенты
Subversion command-line и
TortoiseSVN
Command-line SVN
29
Хранение контента
Тип документации (репозиторий)
Ветки репозитория
– разработческая
– стабильная
Языковые каталоги внутри ветки
Документы
30
Структура документа
DITA-топики (тексты)
image – иллюстрации
work – рабочие материалы
31
Хранение
Надежность
Прозрачность
Удобство
32
Учет Учет
33
Как работает?
Документы
Задачи
Люди
34
Сделали так
35
Практические советы
36
Наши находки
Живые картинки
Отладчики HTML-страниц в браузерах
Организация репозитория для хранения документации
Система учета документации в багтрекере
37
Спасибо за
внимание!
38
Куненко Екатерина
разработчик пользовательской
документации
Клуб техписателей clubs.ya.ru/x-plain
