Хочешь получать новые знания про тимлидство? Подписывайся в Telegram на Teamlead Good Reads!

# Техническая документация

# Описание

Техническая документация подразделяется на пользовательскую и внутреннюю. Пользовательская документация включает в себя инструкции по использованию и установке продукта, описания API, системные требования и прочие документы, предназначенные для конечного пользователя. Внутреннюю документацию в свою очередь можно разделить на продуктовую (описания архитектуры проекта, мануалы по разворачиванию сред разработки, воспроизведению результатов экспериментов, UX документация) и процессуальную (гайдлайны по написанию кода и процедуре code review, документацию по командным процессам, отчёты для менеджмента, планы и roadmaps).

# Почему ветка важна?

Для тимлида:

  • Помогает всегда оставаться в курсе актуального состояния проекта и делиться этой информацией с бизнесом
  • Облегчает процесс онбординга новых членов команды
  • Упрощает коммуникацию с пользователями и stakeholders

Для команды

  • Значительно снижается сложность вникания в новый проект
  • Всегда есть актуальный референс, любой член команды может понять, что происходит в других частях проекта
  • Увеличивается bus factor, происходит распространение знания внутри команды
  • Зачастую сам процесс написания документации улучшает понимание архитектуры проекта и приводит к обнаружению багов или появлению новых идей

Для пользователей

  • Легче пользоваться продуктом, возникает меньше вопросов и ошибок

# Что будет, если её не делать?

  • Внутренняя документация
    • Новые сотрудники будут тратить значительно больше времени на погружение в проект. Также они будут отнимать драгоценное время у членов команды, задавая вопросы, которые легко могли быть покрыты документацией
    • Проект будет обрастать незадокументированными фичами, знание о которых будет иметься лишь у нескольких людей, и даже эти люди в какой-то момент о них забудут
  • Пользовательская документация
    • Возрастает нагрузка на техническую поддержку
    • Увеличивается недовольство пользователей

# На кого может быть делегирована?

На любого разработчика или технического писателя

# Примеры поведения

# Примеры плохого поведения

  • Обновление документации не включается в Definition of Done или не выносится отдельными PBI
  • Затраты времени на написание документации не учитываются при планировании
  • Документация не версионируется
  • Важные изменения документации не проходят процедуру ревью
  • Документация написана слишком длинно и нудно, содержит устаревшую и ненужную информацию
  • Документация пишется не итеративно, а огромными пластами
  • Документация пишется "для галочки", её ценность для команды и пользователей не определена, и её никто не читает

# Примеры хорошего поведения

  • У команд есть единые шаблоны, правила оформления и стиля для создания документации
  • У каждого документа имеется понятная целевая аудитория (пользователи, другие команды, члены команды, менеджмент)
  • Документация хранится в едином удобном месте с функцией поиска, а не раскидана по Google Docs, Confluence, Wiki, Redmine и бумажкам в офисе
  • Используется методология Docs-as-code - документация пишется в текстовом редакторе (например, в формате Markdown), хранится в репозитории, версионируется, тестируется и проходит процедуру peer review, считаются метрики качества (например, readability), новые версии автоматически публикуются
  • Документация хорошо оформлена, важные места выделены и бросаются в глаза
  • Документация содержит ссылки на другие релевантные документы
  • Документация время от времени тестируется на актуальность
  • Обновление документации автоматизируется (насколько это возможно)
  • Появление новой важной документации сопровождается туториалами и воркшопами для целевой аудитории
  • Документация содержит средства визуализации (диаграммы, графики)

# Способы прокачки

# Практика

  1. Полезно читать документацию опенсорсных проектов и других команд и заимствовать лучшие идеи
  2. Регулярно структурируйте имеющуюся документацию и оценивайте её качество для разных частей проекта
  3. В запущенных случаях может быть полезен внешний аудит документации
  4. Для каждого типа документации нужно определить оптимальный способ написания (по ходу разработки vs document late)
  5. Найдите правильный баланс между отсутствием документации и избыточной документацией. Соберите обратную связь от разных групп (разработчики, пользователи, тестировщики, другие команды)
  6. Не бойтесь пробовать нестандартные формы документации - например, видео-дискуссии или подкасты

# Консультации

# Теория

# Подкасты

# Статьи