# Техническая документация
# Описание
Техническая документация подразделяется на пользовательскую и внутреннюю. Пользовательская документация включает в себя инструкции по использованию и установке продукта, описания API, системные требования и прочие документы, предназначенные для конечного пользователя. Внутреннюю документацию в свою очередь можно разделить на продуктовую (описания архитектуры проекта, мануалы по разворачиванию сред разработки, воспроизведению результатов экспериментов, UX документация) и процессуальную (гайдлайны по написанию кода и процедуре code review, документацию по командным процессам, отчёты для менеджмента, планы и roadmaps).
# Почему ветка важна?
Для тимлида:
- Помогает всегда оставаться в курсе актуального состояния проекта и делиться этой информацией с бизнесом
- Облегчает процесс онбординга новых членов команды
- Упрощает коммуникацию с пользователями и stakeholders
Для команды
- Значительно снижается сложность вникания в новый проект
- Всегда есть актуальный референс, любой член команды может понять, что происходит в других частях проекта
- Увеличивается bus factor, происходит распространение знания внутри команды
- Зачастую сам процесс написания документации улучшает понимание архитектуры проекта и приводит к обнаружению багов или появлению новых идей
Для пользователей
- Легче пользоваться продуктом, возникает меньше вопросов и ошибок
# Что будет, если её не делать?
- Внутренняя документация
- Новые сотрудники будут тратить значительно больше времени на погружение в проект. Также они будут отнимать драгоценное время у членов команды, задавая вопросы, которые легко могли быть покрыты документацией
- Проект будет обрастать незадокументированными фичами, знание о которых будет иметься лишь у нескольких людей, и даже эти люди в какой-то момент о них забудут
- Пользовательская документация
- Возрастает нагрузка на техническую поддержку
- Увеличивается недовольство пользователей
# На кого может быть делегирована?
На любого разработчика или технического писателя
# Примеры поведения
# Примеры плохого поведения
- Обновление документации не включается в Definition of Done или не выносится отдельными PBI
- Затраты времени на написание документации не учитываются при планировании
- Документация не версионируется
- Важные изменения документации не проходят процедуру ревью
- Документация написана слишком длинно и нудно, содержит устаревшую и ненужную информацию
- Документация пишется не итеративно, а огромными пластами
- Документация пишется "для галочки", её ценность для команды и пользователей не определена, и её никто не читает
# Примеры хорошего поведения
- У команд есть единые шаблоны, правила оформления и стиля для создания документации
- У каждого документа имеется понятная целевая аудитория (пользователи, другие команды, члены команды, менеджмент)
- Документация хранится в едином удобном месте с функцией поиска, а не раскидана по Google Docs, Confluence, Wiki, Redmine и бумажкам в офисе
- Используется методология Docs-as-code - документация пишется в текстовом редакторе (например, в формате Markdown), хранится в репозитории, версионируется, тестируется и проходит процедуру peer review, считаются метрики качества (например, readability), новые версии автоматически публикуются
- Документация хорошо оформлена, важные места выделены и бросаются в глаза
- Документация содержит ссылки на другие релевантные документы
- Документация время от времени тестируется на актуальность
- Обновление документации автоматизируется (насколько это возможно)
- Появление новой важной документации сопровождается туториалами и воркшопами для целевой аудитории
- Документация содержит средства визуализации (диаграммы, графики)
# Способы прокачки
# Практика
- Полезно читать документацию опенсорсных проектов и других команд и заимствовать лучшие идеи
- Регулярно структурируйте имеющуюся документацию и оценивайте её качество для разных частей проекта
- В запущенных случаях может быть полезен внешний аудит документации
- Для каждого типа документации нужно определить оптимальный способ написания (по ходу разработки vs document late)
- Найдите правильный баланс между отсутствием документации и избыточной документацией. Соберите обратную связь от разных групп (разработчики, пользователи, тестировщики, другие команды)
- Не бойтесь пробовать нестандартные формы документации - например, видео-дискуссии или подкасты