Организации, которые занимаются разработкой и поддержкой программного обеспечения, сталкиваются со множеством уникальных трудностей. Однако с некоторыми из этих трудностей сталкиваются все организации-разработчики. Одна из таких трудностей – помочь новым членам команды максимально быстро познакомиться с технической средой, стандартами разработки, правилами именования, техническими средствами для сборки и развёртывания, стандартами в области контроля версий и так далее. Дейв Николетте заинтересовался дискуссией, возникшей в социальной сети Twitter после поста следующего содержания:
Большое внимание уделяется документации для конечных пользователей: инструкции по установке, документация по API и тому подобное. Но какую документацию вы используете, чтобы помочь новым разработчикам быстрее включится в работу?
В ответ звучали разные предложения, например:
- Диаграммы;
- Блок-схемы;
- Модель C4;
- Комментарии в коде;
- Порядок запуска сборки;
- Детальные функциональные спецификации.
Основная проблема с подробной документацией, по мнению автора, заключается в том, что такая документация быстро перестаёт отражать текущее состояние продукта. К тому времени, когда, например, диаграмма готова для публикации, она может оказаться неактуальной.
Диаграммы и описания с избыточной детализацией не слишком полезны по нескольким причинам. Во-первых, из-за уровня детализации можно с уверенностью сказать, что документация быстро устареет. Во-вторых, из-за большого объёма материала крайне маловероятно, что новые члены команды его прочитают. А если и прочитают, мало что запомнят.
Какая же документация может быть полезна? По мнению автора, наиболее полезными для понимания текущей ситуации в новой среде являются следующие типы документации:
- Контекстная диаграмма каждой важной системы или каждого важного компонента системы, которые необходимо будет поддерживать;
- Высокоуровневая блок-схема связей основных компонентов системы, показывающая их взаимодействие друг с другом.
Конкретные методы моделирования и графические инструменты при этом не важны.
Когда же приходит время погрузиться в код, автору лучше всего помогают следующие виды документации:
- Исполняемые тестовые пакеты для нескольких уровней абстракции, правильно изолированные;
- Действительно полезные комментарии в системе контроля версий;
- Комментарии, которые среда разработки собирает и показывает во время работы. Например, rdoc, Javadoc и тому подобные.
По мнению автора наиболее полезной является контекстная документация в виде всплывающих сообщений, которая появляется при написании и тестировании кода. Другие формы низкоуровневой документации, по мнению авторы, попросту не нужны.
