Какая документация нужна, чтобы быстро включиться в работу

Организации, которые занимаются разработкой и поддержкой программного обеспечения, сталкиваются со множеством уникальных трудностей. Однако с некоторыми из этих трудностей сталкиваются все организации-разработчики. Одна из таких трудностей — помочь новым членам команды максимально быстро познакомиться с технической средой, стандартами разработки, правилами именования, техническими средствами для сборки и развёртывания, стандартами в области контроля версий и так далее. Дейв Николетте заинтересовался дискуссией, возникшей в социальной сети Twitter после поста следующего содержания:

Большое внимание уделяется документации для конечных пользователей: инструкции по установке, документация по API и тому подобное. Но какую документацию вы используете, чтобы помочь новым разработчикам быстрее включится в работу?

В ответ звучали разные предложения, например:

  • Диаграммы;
  • Блок-схемы;
  • Модель C4;
  • Комментарии в коде;
  • Порядок запуска сборки;
  • Детальные функциональные спецификации.

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

Диаграммы и описания с избыточной детализацией не слишком полезны по нескольким причинам. Во-первых, из-за уровня детализации можно с уверенностью сказать, что документация быстро устареет. Во-вторых, из-за большого объёма материала крайне маловероятно, что новые члены команды его прочитают. А если и прочитают, мало что запомнят.

Какая же документация может быть полезна? По мнению автора, наиболее полезными для понимания текущей ситуации в новой среде являются следующие типы документации:

  • Контекстная диаграмма каждой важной системы или каждого важного компонента системы, которые необходимо будет поддерживать;
  • Высокоуровневая блок-схема связей основных компонентов системы, показывающая их взаимодействие друг с другом.

Конкретные методы моделирования и графические инструменты при этом не важны.

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

  • Исполняемые тестовые пакеты для нескольких уровней абстракции, правильно изолированные;
  • Действительно полезные комментарии в системе контроля версий;
  • Комментарии, которые среда разработки собирает и показывает во время работы. Например, rdoc, Javadoc и тому подобные.

По мнению автора наиболее полезной является контекстная документация в виде всплывающих сообщений, которая появляется при написании и тестировании кода. Другие формы низкоуровневой документации, по мнению авторы, попросту не нужны.

ITIL ITIL Practitioner — новый учебный курс 2016

Правильный следующий шаг после ITIL Foundation.
 

Узнайте больше!

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Ближайшие мероприятия

Зарегистрируйтесь, чтобы получить больше полезных знаний:

СЕН
27
ОКТ
1