Context is king
Documentation isn’t just a legacy habit we keep around out of inertia. It is still being used. Users still need to know how to use a system. Employees still need to understand how to perform their tasks, go through onboarding, and build a mental model of the system they are about to work with.
AI automates a lot of work, but it hasn’t replaced everything. And in an interesting twist, it has actually increased the number of consumers of documentation.
Documentation is no longer human-only.
New consumers of documentation
AI agents
We used to have README.md files. Now we added Agents.md to the set. They act as boot instructions for AI agents. They describe what the system is, what it is allowed to do, and—just as importantly—what it must never do.
In this sense, documentation becomes a set of guardrails. Without them, an AI agent will still act, but it will do so by guessing.
RAG-based systems and vectorized knowledge bases
When documentation is indexed and vectorized, it becomes something you can ask questions about. Instead of searching through files manually, you can query the system itself. The quality of the answers is tightly coupled to the quality of the documentation. Garbage in, garbage out—just faster.
In both cases, context is king. And context does not magically emerge from code.
Documentation as a semantic layer over code
Code explains how something happens.
Documentation exists to explain everything else:
- Why the system exists
- What must never change
- Where assumptions live
- What trade-offs were made
- Why an AI (or a human) should care
This information is largely invisible to static analysis. An AI reading the code can follow control flow, but it cannot reliably infer intent. It does not know which parts are accidental and which parts are sacred.
Without documentation, an AI scans the repository and makes assumptions.
With documentation, it follows constraints, architecture, and shared vocabulary.
This is also why obvious comments and line-by-line explanations are mostly pointless. If the code already says what it does, repeating it adds little value. The real leverage is in documenting system boundaries, invariants, and the reasons why this exists at all.
AI changed who does the work, not what work exists
The work of documentation did not disappear. It was redistributed.
Before AI, the typical flow looked like this:
- Writing: medium to high effort
- Reviewing: low to medium effort
With AI, the flow looks different:
- Writing a prompt: low to medium effort
- Reviewing the output: medium to high effort
Writing is now cheap. AI has commoditized first drafts.
On the other hand judgment is expensive. Especially that AI tends to be very verbose.
Humans still own truth, intent, and correctness. Review takes more time because it now involves new kinds of checks:
- Detecting hallucinations
- Removing unjustified confidence
- Aligning the tone of the documentation with reality, not aspiration
Hallucinations and unjustified certainty are the new documentation bugs.
Consistency over creativity: the role of templates
Generative AI is a powerful tool for writing documentation, but it is probabilistic by nature. If you are not specific enough and do not enforce any structure, it happily produces Star Trek–style sci‑fi mumbo-jumbo filled with confident buzzwords.
Good prompts for documentation tend to be very explicit. They usually:
- Specify the audience
- Specify the scope
- Specify the purpose
- Specify what not to include
Documentation prompts are closer to contracts than to creative writing exercises.
Templates help a lot here. You can think of them as prompt stabilizers. They reduce variance and push the AI toward something predictable and useful.
Templates reduce:
- Cognitive load for readers
- Prompt complexity
- Review time
They work especially well for:
- Architecture Decision Records (ADRs)
- RFCs (Request For Comments)
- Microservice READMEs
- Runbooks
Consistency beats creativity when the goal is understanding.
Documentation as cost control in the age of tokens
AI answers are:
- Fast
- Expensive
- Ephemeral
Documentation is:
- Slow to produce
- Cheap to reuse
- Durable
Historically, the purpose of documentation was to scale knowledge and save costs. Instead of answering the same question a hundred times, you wrote it down once and shared the link.
That logic still holds, but the economics have changed. Today, someone can ask the AI about the codebase and get an answer immediately. Then another person comes in and asks the same question again. Each time, the AI scans, reasons, and consumes tokens.
A useful pattern here is human-in-the-loop knowledge crystallization:
Answer the question once with AI → review it → turn it into documentation.
Over time, good documentation reduces prompt size and search space. The AI can answer future questions by relying on the documented context instead of re-deriving everything from scratch.
Documentation is infrastructure
We didn’t stop needing documentation. We just stopped writing it only for ourselves.
In the AI era, documentation is no longer a static artifact created exclusively for humans. It is a shared context layer for humans and machines.
