Принцип "Код - лучшая документация" замечательно работает для маленьких проектов и небольших кодовых баз. Но чем больше людей в команде, чем чаще они меняются, тем больше коммуникаций необходимо делать помимо работы с кодом.

Чтобы повысить эффективность работы в растущих командах необходимо в дополнение к коду начать документировать наиболее "горячие" места проекта.

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

Определить какой тип документации вам нужен 

Типы бывают следующие:

 - сопроводительная документация

 - вспомогательная документация

 - проектная документация

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

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

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

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

Поддерживать в синхронизированном состоянии  документацию и код очень трудно, поэтому лучше когда эти задачи не пересекаются.

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

Например, я использую следующий набор документов:

1. Постановка и описание задачи;

2. Архитектурные решения (ADR) 

3. README 

Документы удобно использовать, чтобы упростить онбординг новых разработчиков, уменьшить количество вопрос к коллегам, дать базовые понимание архитектуры проекта.

Если писать документацию ради документации, то ничего хорошего из этого не получится.

Например, ADR состоит из стандартных разделов:

- контекст (описание задачи)

- варианты решений

- принятое решение

- достоинства и недостатки принятого решения.

Людям проще читать и писать документ по типовой структуре.

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

Когда процесс документирования и структура документов еще не отлажены есть небольшое замедление в работе, которое со временем компенсируется за счет времени ранее используемого для общения и объяснения типовых вещей.

Пример, как выглядит процесс документирования в NarisApp

1. Заводим Эпик с набором пользовательских историй
2. Документ с постановкой задачи со следующей структурой:  

   - описание (истории)

   - понятия или сущности (словарь)

   - варианты использования (useCase)

   - варианты реализации (общие решения)

3. ADR в котором окончательно фиксируются решения по архитектуре
4. Реализация в кодовой базе

Такой минимальный набор документирования помогает сформировать проектное мышление у команды, помогает продумать решение до написания кода, найти слабые места и белые пятна в постановке задачи.