In engineering, documentation tends to be unloved. "Good code doesn't need comments." "If you need to explain it, you wrote it wrong."
Sometimes that's true. When the team is stable, turnover is zero, and context lives in people's heads for years.
But in reality, people come and go, projects grow, and context disappears faster than the code changes.
The classic scenario
Someone from the team comes to you and asks: "Why did we do it this way N months ago?"
And you sort of remember there were reasons. Some circumstances. Some constraints. Some important context.
But honestly — not quite anymore.
So the person runs in circles, gathering information bit by bit, and a decision that was once deliberate turns into folklore. Onboarding becomes a nightmare, every new hire bothers their buddy endlessly, and decisions exist — but nobody remembers why they were made.
Documentation outside the code
There's a separate pain point: Confluence, Notion, Google Docs. It can look great, but it almost never surfaces at the right moment and goes stale remarkably fast.
Now add AI to the picture
For agents and RAG systems, the situation is even worse. AI can see what the code does, but it doesn't understand why.
Why this approach was chosen. What trade-offs were accepted. Where the boundaries of acceptable behavior are.
Without documentation, the system is just a set of facts with no meaning.
What actually helps
This isn't about a README that says "how to run the project." It's about:
- ADRs — why a decision was made
- Architecture docs — how the system is structured and where the boundaries are
- Explicit contracts and constraints — what's allowed, what's not
Documentation that explains intent, not code.
"But it always goes stale"
Fair — if you write it manually and treat it as an afterthought. But that's no longer an excuse.
Documentation can be maintained by agents, validated alongside code, and made part of the pipeline — not a task for "when there's time."
Documentation is the memory of a system. Without it, you're constantly losing context — for humans and for AI alike.
And a system without memory is always expensive to maintain.