Опорная идея
Документация пишется не для абстрактного читателя. У каждого документа есть audience, task, prerequisites, context and success criteria. Новичку нужен tutorial, опытному инженеру — reference, дежурному — runbook, архитектору — decision record.
Если смешать все форматы в один документ, он становится длинным и плохо помогает всем сразу.