Documentation that is not maintained is worse than no documentation. The docs-as-code approach aligns documentation with the same workflows as code, so it stays alive.
Technical documentation suffers from a universal problem: it ages poorly. Written once during design, it is no longer updated when things change. Two years later, it describes a system that no longer exists. The problem is not lack of motivation — it is the cost of updating, decoupled from the code itself. The solution: treat documentation like code.
The docs-as-code approach stores documentation in the same repository as the code, in Markdown or AsciiDoc. Documentation updates are part of the same PR as code changes — no PR accepted without updated docs if behavior changes. Tools like MkDocs, Docusaurus or VitePress generate a clean static site from Markdown files. The docs are versioned, reviewed, testable.
Living docs go further: they are generated from the code itself. OpenAPI specifications generated by springdoc, class diagrams generated by PlantUML from annotations, code examples extracted directly from tests — everything that can be generated automatically avoids desynchronization. Notion remains useful for product documentation and team processes, but for technical documentation, proximity to code is unbeatable. The golden rule: if documentation can desynchronize from code, it will.
- Store technical docs in the repo, in Markdown
- Require doc updates in functional PRs
- Generate what can be generated (OpenAPI, diagrams)
- Reserve Notion for product and organizational docs