Документация. Документация никогда не меняется

Хочу сегодня поговорить об основном артефакте аналитика - документации. Сколько ни работал, практически всегда дока ведется с какими-то косяками. Как минимум, присутствует технический долг или некоторые разделы теряют актуальность. А «задачи на развитие» звучит как «ну, у нас есть сервис, который кто-то когда-то сделал, но не описал, вот займись».

Давай про доку, которую ведут в конфе (или любой другой вики-подобной системе). Я вижу 2 подхода, как можно действовать: создавать описание системы (и прямо в нем вносить изменений) и хранить описание отдельно, а «постановки» на разработку отдельно.

С описанием системы плюс минус понятно - мы по слоям описываем, что у нас есть. Базы данных, с таблицами, атрибутами и связями между ними. Методы бэка, которые вызываются на каждом из слоев. Топики брокера, с указанием консьюмеров и продюсеров. Наконец, фронтенд, где показываем макеты и поведение элементов. Идеально, если у нашего проекта есть отрисованная архитектура, которую можно использовать для «взгляда сверху».

Как вносить изменения? В каждом слое вносишь изменение цветом, указываешь, какая логика добавилось, что удалилось. В истории изменений и в задаче пишешь, какой цвет использовался. Также, в задаче коротко описываешь суть и прикладываешь набор ссылок. На выходе получаем:
1) Таску, где коротко описано, что нужно сделать.
2) Страницы конфы, где уже выделены конкретные куски, которые разрабу нужно поправить
В момент, когда задача заливается в прод, все это добро нужно перекрасить, так будет понятно, что функционал крутится в боевой среде.

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

И второй подход - описание системы отдельно, «постановки» отдельно. Описание создается точно также, единственное, туда не вносятся изменения цветом.

А вот «постановки» - это страницы в конфе, где описываются все моменты, которые надо изменить. Вносим такую-то правку в бд (ссылка на бд), вносим правку в бэк (ссылка на бэк) и т.д. Это может быть удобно для разработчика, ведь ему не надо прыгать по страницам, но минусов, как по мне, сильно больше.

1) Тебе придется делать двойную работу - писать в одном месте, и переносить в другое. Это явно дольше, чем перекрасить текст.
2) Описание системы сто процентов будет неактуальным, потому что где-то там есть «постановка» в которой логика будет меняться. Плюс кто-то забудет внести изменения после выкатки и все, кранты.
3) Типичная ситуация - коллега внес изменения в сервис, его «постановка» ждет разработки. Тебе прилетает задача, которая предполагает внесение правок в тот же сервис. Но, ты уже можешь работать по неактуальной документации. Да, есть дейлики, где ты слушаешь, кто чем занят, но надеяться на «авось услышу» глупо.

Я не сторонник второго подхода, считаю, что он порождает слишком много лишней работы. А что думаете вы? Как ведется документация у вас?