Документация, которую никто не читает, и документация, которую читают. В чём разница

Работал в командах, где документация была, и где её не было. И в командах, где она была, но не работала. Последнее - хуже всего.

Документация, которую не читают, обычно такая: большие страницы в Confluence с заголовками и подзаголовками. Написана когда-то давно. Возможно, даже правильно написана. Но устарела, и никто не знает насколько.

Документация, которую читают, обычно такая: короткая заметка прямо рядом с задачей. «Почему мы сделали именно так». «Что пробовали до этого». «Что точно не трогать и почему». Как правило, написана человеком, который только что через это прошёл.

Разница не в формате и не в инструменте. Разница в том, когда написана и зачем. Полезная документация пишется сразу после того, как разобрался, пока контекст свежий. И для конкретного читателя. Для того, кто столкнётся с этим следующим.

Большой текст с правильной структурой и устаревшим содержимым не помогает. Помогает заметка из двух абзацев, написанная вчера и по сути.

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

Обновляйте документацию при каждом изменении кода, включайте это в Definition of Done.

Ежеквартально проверяйте документацию на актуальность, удаляйте устаревшее или лучше архивируйте для сохранения истории.

Пишите понятные заголовки, стабильные якоря и прописывайте единые шаблоны.

Как у вас в команде устроена документация, которая реально используется?