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