КОДЕКС

Почему не следует использовать Confluence для документации по коду

Это всегда устарело

Большинство из нас были там - это почти обряд посвящения: следование руководству в Confluence, которое ужасно устарело. Человек, который его написал, очень гордился деталями во время создания, добавил много скриншотов и, возможно, даже несколько анимированных изображений. К сожалению, панель меню на снимке экрана больше не существует, а кнопка, необходимая для выполнения одного из шагов, удалена.

Confluence и вики быстро устаревают

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

Излишние объяснения

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

Недостаточные объяснения

С другой стороны, отсутствие документации может увеличить объем функции. Иногда разработчики, особенно в спешке, делают короткие записи, которые понимают только они. Заметки служат для них удобным справочником, но непригодны для тех, кто берет на себя проект. В этих ситуациях стоимость ухода разработчиков увеличивается.

Повторение чужой документации

Иногда люди документируют без надобности. Например, объясняя, как выполнить интеграцию со сторонними библиотеками. Обычно эта информация легко доступна на стороннем веб-сайте.

Диаграммы

Confluence не ориентирован на архитектурные диаграммы. Из-за этого разработчики передают изображения внешним редакторам, экспортируя и вставляя файлы PNG. Эти диаграммы могут быть сложными, с десятками узлов. Они редко обновляются после создания, особенно когда автор больше не работает в компании. Никто не хочет создавать его с нуля.

Документы технических требований (TRD)

TRD описывают, как будет реализована функция. Они показывают мыслительные процессы, перечисляют альтернативные решения и записывают выводы. Принятие к сведению решений по коду - отличная идея, но есть лучшие способы сделать это в репозитории кода.

На практике TRD могут быть полезны для немедленной необходимости улучшить совместную работу, но становятся беспорядочными после выпуска соответствующих функций. Иногда разработчики тратят больше времени на их написание и обновление (чтобы удовлетворить процесс), чем на реализацию функции.

Слишком много документов

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

У вики может быть видимая усталость: богатые, организованные документы рядом с незаконченными, заваленными TODO.

Нет экспертной оценки

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

Разработчики этим не пользуются.

Поисковые системы, такие как Google и Bing, друзья разработчиков. Они попадут на веб-сайты с официальной документацией, рецензируемыми образцами источников или ответами на такие вопросы, как StackOverflow. Слияние - это последнее место, куда нужно смотреть, если только знание не является строго внутренним или если они не знают, что оно существует для многих людей.

Заключение

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