Documentation without writing it by hand 📖

TL;DR: Documentation generated by an agent is quick to produce, but every statement must be verified. Wrong documentation is worse than no documentation because someone will read it and rely on it. The trick is not to generate less, but to verify more.

The documentation problem 📝

Documentation is that thing everyone knows is important and nobody wants to do. It is boring, it gets obsolete quickly, and the cost/benefit ratio always seems unfavorable. Then a coding agent arrives and says: “I can generate it for you.” And it is true — it can. But there is a subtle problem.

Correct documentation is extremely useful. Wrong documentation is worse than no documentation, because someone will read it, believe it, and make decisions based on false information. And the beauty of it is that wrong documentation looks right — it is written with the same tone, the same format, the same structure as real docs. It just says things that do not match the code.

The risk is not having too little documentation. The risk is having documentation that seems reliable but is not.

What the agent can do 🤖

A coding agent is excellent at:

• Generating READMEs — project description, installation, usage, contribution.
• Documenting APIs — extracting signatures, parameters, return types from code.
• Creating ADRs — documenting architectural decisions and their context.
• Producing changelogs — summary of changes between versions.
• Writing contribution guides — how to contribute, standards, review process.

The point is that the agent extracts from code, it does not invent. But sometimes extraction is imperfect and the agent can misinterpret a pattern, extrapolate a behavior that does not exist, or simplify a complex flow.

Verification as a skill 🔍

The hard part is not generating documentation. It is verifying it. And verification requires competence: you need to understand the code well enough to know whether the documentation describes it correctly.

Some concrete rules:

• Every statement must be verifiable — if the doc says “the endpoint accepts a parameter id of type string”, verify that is actually the case.
• Compare with actual code — not with what it “should” be.
• Verify edge cases — does the doc mention all possible errors? All behaviors?
• Update the doc when code changes — documentation lives with the code, it is not an appendix.

In Documentation from a codebase we explore the complete workflow: from choosing the format to verifying coherence, from doc-as-code to continuous updates.

Doc-as-code: the right path 📚

The concept of doc-as-code is simple: documentation lives in the repository alongside the code. It is versioned, reviewable, part of CI. It is not a forgotten Wiki, not a lost Google Drive: it is a file that evolves with the project.

This means:

• Same repo, same branch — docs are close to the code they document.
• Same review process — docs go through PRs like code.
• Same automation — docs are tested (at least for coherence) alongside code.

Documentation is not an extra: it is an architectural component. Treat it like you treat code.

The paradox of generated documentation 🎯

Here is the paradox: the easier documentation is to generate, the more critical it becomes to verify it. Before, when writing docs took an hour, whoever wrote them necessarily knew them. Today, when an agent generates them in 30 seconds, whoever verifies them might never have read them.

The solution is not to generate less. It is to verify more. Every line of generated documentation should be read by someone who knows the code. It is not a cost: it is an investment in the series’ credibility.

And perhaps the simplest lesson: documentation is not an act of generation. It is an act of verification. The agent writes, you verify. The agent extracts, you confirm. The agent produces, you certify. Only then is documentation reliable. Only then is it worth existing.