В докладе речь пойдёт об особенностях написания документации для разработчиков. Мы поговорим о том, какая предварительная подготовка нужна для создания документов. Обсудим специфику взаимодействия с консультантами, процесс разработки, рецензирования и поддержки документации.

1. 1

2. 2
Особенности
документирования
для разработчиков
Юрий Никулин
Руководитель группы документирования поиска и технологий
Гипербатон, Москва, 24 мая 2014 года

3. 3
Разработка документации
Инструменты
Комплект документов
Уровень подготовки писателя
Процесс разработки

4. 4
Почему документация для
разработчиков
Не каждый технический
писатель возьмется
готовить такую
документацию

5. 5
Инструменты и комплект
документации
Из чего выбирать и что писать

6. 6
Инструменты
Разметка
DITA / Wiki / Markdown
Генерация из кода
Doxygen / JSDOC
Подготовка схем
Visio / Dia
Подготовка скриншотов
Jing + Snagit / GIMP + Dia
Про инструменты, используемыe в Яндексе:
http://video.yandex.ru/users/ya-events/view/2610
Минимально возможный набор

7. 7
Комплект
Не делаем универсальные документы
Исходим из потребностей целевой
аудитории
Отталкиваемся от сложности задачи

8. 8
Подготовка
технического писателя
Необходимые навыки

9. 9
Навыки технического писателя
Профессиональные
– структурирование
– ясность изложения
– обработка больших объемов информации
В предметной области
– глубокое погружение

10. 10
Как писать для
разработчиков
Адаптация процесса под документирование
для разработчиков

11. 11
Основные этапы разработки
Консультируемся
Пишем
Проверяем факты
Поддерживаем

12. 12
Консультации
Правильно общаться с разработчиком

13. 13
Главное в консультациях
Исчерпывающая информация
Оптимальное количество времени

14. 14
Как консультироваться
Войти в образ
разработчика
Задавать только нужные
вопросы
Минимизировать шум

15. 15
Разработка документа
Как пишем

16. 16
Портрет разработчика
Недостаток времени
Особое восприятие
информации
Свой язык

17. 17
Недостаток времени
Отталкиваемся
от решаемых задач
Придерживаемся
прозрачной структуры
Пишем лаконично
Фиксируем концепции
Идем навстречу привычкам

18. 18
Особое восприятие информации
Стиль
Формат представления
Язык
Примеры
Особенности оформления
документации
Адаптируемся под конкретную целевую аудиторию

19. 19
Свой язык
Отколоть ветку == отщепить ветку == создать ветку от ветки
Слушаем команду
Читаем открытые источники
– форумы
– Stack Overflow

20. 20
Рецензирование
Обходим подводные камни

21. 21
Основные сложности
Задержки с вычиткой
Вкусовщина
Полярные мнения

22. 22
Задержки с рецензированием
Мозолим глаза
Ставим задачи в баг-трекере
Даем фрагменты документа
Вручаем документ маленькими
порциями
Читаем вместе
Индивидуальный подход

23. 23
Вкусовщина
Стилистическая
Оформительская
Разделяем зоны ответственности

24. 24
Полярные точки зрения
Очная ставка
История замечаний

25. 25
Оцениваем итоги рецензирования
Быстро вернули, «все хорошо» – не читали
«Все плохо, ничего не понятно» – не читали
Долго не отдавали, много замечаний – лучший вариант

26. 26
Поддержка
Улучшаем документацию

27. 27
Типы обновлений
Актуализация
Обратная связь
– Прямые обращения
– Статистические данные

28. 28
Подводим итоги
О чем поговорили

29. 29
Документирование для разработчиков
Специфичные инструменты
Погружение в тематику
Особенности коммуникаций
Особый подход к контенту

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

31. 31
Юрий Никулин
Руководитель группы документирования
поиска и технологий
Клуб техписателей clubs.ya.ru/x-plain
yandex-techdoc@yandex-team.ru