Разработка и документирование

Советы и пример того как можно оптимизировать работу команды разработчиков за счет ведения документации.

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

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

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

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

  1. Заводим Эпик с набором пользовательских историй
  2. Документ с постановкой задачи со следующей структурой:
    • описание (истории)
    • понятия или сущности (словарь)
    • варианты использования (useCase)
    • варианты реализации (общие решения)
  3. ADR в котором окончательно фиксируются решения по архитектуре
  4. Реализация в кодовой базе Такой минимальный набор документирования помогает сформировать проектное мышление у команды, помогает продумать решение до написания кода, найти слабые места и белые пятна в постановке задачи.