Documentation is the most abused artifact in software. It incurs all the same costs as writing and maintaining code, but with a fraction of the scrutiny we give to a simple question: is this worth it?
These ten rules are what remains after you strip away the documentation that never earned its place. They are not about writing more. They are about writing only what survives contact with time, entropy, and people.
I
Thou shalt not write documentation unless thou canst define its purpose, its audience, its critical path, and its maintenance.
Answer four questions:
What is this accomplishing?
Who is my audience?
How will they know it exists?
Who will keep it true?
If you cannot answer all four, you are not writing documentation. You are creating a liability. It is the first and most important commandment because documentation exists to save time. If you cannot answer these four questions, you will save more time by writing nothing at all.
II
Thou shalt reach for design before documentation.
A clearer name, a stricter type, a smaller function, or an honest enum will prevent confusion that no comment can cure. Better still, bake the truth into the contract (the type, the schema, the signature), where it is enforced and can never drift. Never write “may be null”; make it nullable. Only once design is exhausted should you fall back to prose.
III
Thou shalt document the why.
To uncover what something does, you can look at the code, and in good codebases, the tests. The how and the what are already available. Capture instead the things they cannot show: why this trade-off, why this constraint, why the obvious approach was rejected. Effort spent outside the why is usually wasted.
IV
Thou shalt honor a single source of truth.
Never record the same fact in two places; the copies will drift, disagree, and teach the reader to trust neither. Link to existing sources. Keep the source of truth where it is most relevant, and most likely to be encountered on the critical path.
This holds even more true for facts you do not own. Do not paste another tool’s install guide into your README. Link to it, and document only where you differ from it.
When a fact is too big to inline, like the reasoning behind a significant decision, give it a single home such as an ADR (Architecture Decision Record) and link to it, instead of repeating it wherever it seems relevant.
Remember, the best source of truth is one that cannot drift at all: either documentation that programmatically dictates behavior (e.g. schema-first GraphQL), or documentation generated straight from the code (e.g. Swagger docs from an OpenAPI spec).
V
Thou shalt place documentation in the path of the one who needs it.
Documentation found too late, or never, is worthless, however well written. Put it where the reader is already standing when the question arises: the file they will open, the schema they will read, the change they will review. If it sits somewhere they must first think to look, assume they never will. Subpar documentation in the right place is worth far more than thorough documentation in the wrong place.
VI
Thou shalt use less detail, not more.
The seven-step walkthrough becomes a lie the moment the process grows an eighth step, and it always does. High-level intent survives change; step-by-step procedure does not. When in doubt, cut. The discipline of deciding what matters is the valuable part, and silence is safer than a detail that will one day mislead.
VII
Thou shalt write plainly.
Plain words, no ceremony, no hand-holding. Write as you would explain it to a capable colleague standing at your desk, not as a specification to be notarized. Jargon and formality do not make documentation more correct, only more likely to go unread.
Structure it to be scanned, not read. People move through a page in an F, catching headings and the first few words of each line before they move on. Lead with the point, keep paragraphs short, and prefer a list to a dense block wherever the content allows.
This is especially true for AI-generated documentation, which often reads as overly complex, verbose, or unnatural. Be vigilant: simplify and clarify it before it enters your codebase. Better yet, spend the time to give your AI tooling guidelines that produce plainer prose from the start.
VIII
Thou shalt keep thy diagrams editable, versioned, and open.
A diagram trapped in a screenshot, or locked behind a tool that demands an account, is a diagram that will never be updated. Draw in text (e.g. Mermaid), or in a format that stays editable alongside your code (e.g. draw.io), so your pictures live in the repository, diff in review, and can be fixed by anyone who spots the drift. And when a diagram grows too dense to read at a glance, split it into several that each answer one question.
IX
Thou shalt reject hierarchical storage.
The folder tree taxes you twice: once when you file a document and must guess the one true branch it belongs to, and again when a reader must guess the same branch to find it. Both guesses are often wrong, and frequently there is no right answer. Prefer flat, tagged, and linked structures, where a document can be found by any of its facets, not only the single path someone chose months ago.
X
Thou shalt treat every document as an untested script in production.
Documentation cannot be tested. No assertion fails when it goes stale, no build turns red, no alarm sounds. It simply misleads, quietly, until someone acts on it. Trust it exactly as much as you would trust an unversioned script running in production with no coverage: warily, and never more than the code it claims to describe.
A good first step
Point an AI agent at this page.
Ask it to turn these principles into a documentation skill for your stack, then let it apply them on every change. That is how this judgment becomes part of your tooling, instead of sitting on a page no one reopens.
Read documandments.com and write a documentation SKILL.md that enforces these ten rules for this codebase.