КОДЕКС
Почему не следует использовать Confluence для документации по коду
Это всегда устарело
Большинство из нас были там - это почти обряд посвящения: следование руководству в Confluence, которое ужасно устарело. Человек, который его написал, очень гордился деталями во время создания, добавил много скриншотов и, возможно, даже несколько анимированных изображений. К сожалению, панель меню на снимке экрана больше не существует, а кнопка, необходимая для выполнения одного из шагов, удалена.
Confluence и вики быстро устаревают
Разработчики работают в репозиториях кода, а не в Confluence. Если они не обновят документацию по каждому изменению, одна пользовательская история может сделать ее устаревшей. Они могут не знать, что документация существует в некоторых случаях.
Излишние объяснения
Добавление простой функции к сложной, неизвестной системе может быть ошеломляющим, особенно при чтении статьи по архитектуре размером с исследовательскую работу. Некоторые авторы упаковывают страницы с подробностями, что является благородным делом. Однако, если вам нужна информация быстро, ее отслеживание может быть утомительным. Слишком много информации может создать ненужную путаницу.
Недостаточные объяснения
С другой стороны, отсутствие документации может увеличить объем функции. Иногда разработчики, особенно в спешке, делают короткие записи, которые понимают только они. Заметки служат для них удобным справочником, но непригодны для тех, кто берет на себя проект. В этих ситуациях стоимость ухода разработчиков увеличивается.
Повторение чужой документации
Иногда люди документируют без надобности. Например, объясняя, как выполнить интеграцию со сторонними библиотеками. Обычно эта информация легко доступна на стороннем веб-сайте.
Диаграммы
Confluence не ориентирован на архитектурные диаграммы. Из-за этого разработчики передают изображения внешним редакторам, экспортируя и вставляя файлы PNG. Эти диаграммы могут быть сложными, с десятками узлов. Они редко обновляются после создания, особенно когда автор больше не работает в компании. Никто не хочет создавать его с нуля.
Документы технических требований (TRD)
TRD описывают, как будет реализована функция. Они показывают мыслительные процессы, перечисляют альтернативные решения и записывают выводы. Принятие к сведению решений по коду - отличная идея, но есть лучшие способы сделать это в репозитории кода.
На практике TRD могут быть полезны для немедленной необходимости улучшить совместную работу, но становятся беспорядочными после выпуска соответствующих функций. Иногда разработчики тратят больше времени на их написание и обновление (чтобы удовлетворить процесс), чем на реализацию функции.
Слишком много документов
Многие вики сталкиваются с одной и той же проблемой: бесчисленное количество документов, созданных примерно в одно и то же время, сопровождаются большим разрывом во времени. Когда компании впервые вводят вики-сайты, они спешат - возможно, это инициатива - чтобы все аккуратно задокументировать, как перемещение мебели в новый дом. Однако, как и при переезде, некоторые коробки не подходят друг другу. Через несколько недель их распаковывают или бросают в кладовку.
У вики может быть видимая усталость: богатые, организованные документы рядом с незаконченными, заваленными TODO.
Нет экспертной оценки
Код можно тщательно изучить на предмет точности, а автоматизированные процессы уменьшают вероятность человеческой ошибки. Документы Wiki, если они внутренние, обычно не проходят проверку. Ответственность за точность информации, правописание и грамматику несет исключительно автор.
Разработчики этим не пользуются.
Поисковые системы, такие как Google и Bing, друзья разработчиков. Они попадут на веб-сайты с официальной документацией, рецензируемыми образцами источников или ответами на такие вопросы, как StackOverflow. Слияние - это последнее место, куда нужно смотреть, если только знание не является строго внутренним или если они не знают, что оно существует для многих людей.
Заключение
Документация неплохая; это просто не подходящее место для кода. Документация по коду должна располагаться рядом с кодом в месте, где часто бывают разработчики.