Разработка и документирование
Принцип "Код - лучшая документация" замечательно работает для маленьких проектов и небольших кодовых баз. Но чем больше людей в команде, чем чаще они меняются, тем больше коммуникаций необходимо делать помимо работы с кодом.
Чтобы повысить эффективность работы в растущих командах необходимо в дополнение к коду начать документировать наиболее "горячие" места проекта.
Я хочу дать несколько советов, которые помогают мне в работе с документацией на проект.
Определить какой тип документации вам нужен
Типы бывают следующие:
- сопроводительная документация
- вспомогательная документация
- проектная документация
- рабочая или пользовательская документация
- техническая документация
Тип документации зависит от того какой проект вы делаете. В стартапе обычно хватает сопроводительной документации. В крупных проектах делается полноценная проектная документация (технорабочий проект).
Минимально дублируйте информацию из кодовой базы
Лучше когда документация описывает основные принципы, понятие, словарь проекта и другие моменты связанные с общим описанием проекта, а код вносит конкретику и дополняет документацию.
Поддерживать в синхронизированном состоянии документацию и код очень трудно, поэтому лучше когда эти задачи не пересекаются.
Сопроводительную документацию стоит начинать с малого
Изначально документирование будет требовать больше времени, пока не войдет в привычку и не будет сформированы навыки ведения документации. Поэтому изначально не стоит делать что-то большое и сложное, можно начать с малого.
Например, я использую следующий набор документов:
1. Постановка и описание задачи;
2. Архитектурные решения (ADR)
3. README
Если что-то можно не документировать, то лучше этого не делать
Документы удобно использовать, чтобы упростить онбординг новых разработчиков, уменьшить количество вопрос к коллегам, дать базовые понимание архитектуры проекта.
Если писать документацию ради документации, то ничего хорошего из этого не получится.
Если писать документацию ради документации, то ничего хорошего из этого не получится.
Максимально типизировать структуру каждого документа
Например, ADR состоит из стандартных разделов:
- контекст (описание задачи)
- варианты решений
- принятое решение
- достоинства и недостатки принятого решения.
Людям проще читать и писать документ по типовой структуре.
Написание документации должно быть частью процесса разработки или быть самостоятельным процессом
Документирование не должно быть опцией (необязательной частью) проекта. Документацию писать не любят и пытаются этого избежать, поэтому наличие документации должно быть требованием, а не правом.
Не бросать документирования при первых трудностях
Когда процесс документирования и структура документов еще не отлажены есть небольшое замедление в работе, которое со временем компенсируется за счет времени ранее используемого для общения и объяснения типовых вещей.
Пример, как выглядит процесс документирования в NarisApp
Пример, как выглядит процесс документирования в NarisApp
1. Заводим Эпик с набором пользовательских историй
2. Документ с постановкой задачи со следующей структурой:
2. Документ с постановкой задачи со следующей структурой:
- описание (истории)
- понятия или сущности (словарь)
- варианты использования (useCase)
- варианты реализации (общие решения)
3. ADR в котором окончательно фиксируются решения по архитектуре
4. Реализация в кодовой базе
4. Реализация в кодовой базе
Такой минимальный набор документирования помогает сформировать проектное мышление у команды, помогает продумать решение до написания кода, найти слабые места и белые пятна в постановке задачи.
