Comments 4
Проблема в том, что документация имеет тенденцию «протухать»: она описывает не ту версию кода, которая сейчас, а ту, которая была, когда документацию писали — как говорится, «человек, у которого одни часы, всегда знает, который час; человек, у которого двое часов, никогда в этом не уверен». Поэтому надо писать самодокументирующийся код.
Как узко...
А коментарии к коду это такая фигня.. Чет все зацикливаются на том как пуговици пришиты (код написан).
Костюм не только из пуговиц состоит.
Обычно возникают проблемы не по коментриям к коду.
А вопросы типа:
А когда и в каком контексте это делали.
Где лежит обсуждение с заказчиком и почему сделано так или не иначе.
А почему вот от этого отказались и выбрали это..
и т.д.
И это все не всегда можно востановить. Переписка теряется.. люди уходят (и на строне заказчика то же). В заявка часто не пишут все. Типа зачем писать "это ж очевидно". А через полгода даже автор это "очевидно" уже не воспринимает как очевидно.
А если в конференции голосовй никто не вел протокол или что то в нем упустил то эту инфу можно вообще только перекрестным допросом извлечь.
У вас проблема:
куски не складываются в цельную картину
что вы (в ответ на это) делаете — автоматизируете создание кусков
Wiki — это как раз и есть движок позволяющий собрать в системные знания разрозненную информацию через ссылки, include страниц и фрагментов (обеспечивая DRY); ещё и за целостностью следит: отслеживает переименования/перемещения страниц; при попытках удалить предупреждает о входящих ссылках. Конкретно упомянутый Confluence, ещё и содержимое задач в Jira позволяет расковырять. Вот это и это и есть живая документация, когда изменения в одном документе или задаче актуализируют документы зависимых компонентов.
Документация как код и автогенерация документации — прекрасные инструменты, но решают совсем другие задачи.
кажется, что если вы не знаете почему выбран терраформ вместо ансибл, то проблема чуть глубже документации..
Может и нет, но кажется именно так..
Секреты передачи знания: переход границ опыта при уходе ключевых инженеров и документирование архива проектов