Documentation Create

Overview

A reader must never have to infer what a sentence means, and must never be asked to take a factual claim on trust. This skill is the long form of R-210 (complete sentences with full context, leaning toward verbose).

Two obligations follow from that. Every explanation carries its context, so the reader is not reconstructing what you meant. Every fact carries its support, so the reader can check you rather than believe you.

Terseness is not the goal and never was. These rules add words. A document that is short because it omitted the reasoning has failed; a document that is long because it explained causes, effects, mistakes and trade-offs has succeeded.

When to Use

Use for any document whose job is to make a reader understand something: explainers, onboarding docs, architecture notes, READMEs, rationale logs, post-mortems, incident write-ups, briefings, reports, and design docs.

Do not use for reference material with no prose: a changelog of one-line entries, a generated API dump, a config file with inline comments.

The four sentence-level faults

These are the recurring ways a sentence asks the reader to do work the writer should have done. Scan the finished draft for each one.

Fault	What it looks like	Why it fails	The fix
Definite reference to something never introduced	"The five states are separated on six axes."	"The five states" is written as though the reader already knows them. They do not.	Name them at first use: "solid, weak, no match, refusal, error".
A count without its items	"They differ on six visual axes."	The number tells the reader there is a list and then withholds it. It also lets the writer avoid checking whether six is right.	List all six: "container, edge, indent, shadow, chip construction, content mass".
A judgement without its reason	"This is the most interesting failure in the submission."	A ranking with no criterion. The reader cannot agree, disagree, or use it.	Give the reason, or delete the ranking: "This one matters most because it is reproducible in thirty seconds and it contradicts the document's opening claim."
A comparison missing a term	"The scorer is weaker than the signal it feeds."	Names one side and a direction, but not the dimension or the other side.	Name both sides and what is being compared: "The chip correctly reports the category the server assigned. The scoring that decides that category matches raw substrings, so the category is often wrong."

A useful test for all four: read the sentence aloud with no surrounding context. If it raises a question it does not answer, it is one of these.

The verification contract

Everything in this section is about the same failure: writing what a system is supposed to do instead of what it does.

Before any factual claim about a system goes into a document:

Claim type	What is required
The system behaves a certain way	Run it. Reading the code is not running it. Put the actual output in the document.
A file, function or constant does something	Open the file. Cite it by path and name.
A quoted string	Copy it from the source. Never reconstruct a quotation from memory or from a paraphrase.
A count of anything	Count them. Then check the count against the list you wrote.
Anything sourced from a summary document	Check the summary against the thing it summarizes. Summaries drift from what they describe, and a summary is where most inherited errors come from.

The rule about intent. Design documents describe what a system was built to do. That is not evidence that it does it. If you are writing "this design prevents X", either demonstrate that X cannot happen, or write "this design is intended to prevent X" and say whether you checked.

Failure modes observed in testing

Three agents were asked to write the same technical explainer from a real codebase, with no guidance. What they produced:

• All three described intent as achieved behaviour. None ran the system. Two wrote absolute guarantees ("no path by which a weak guess can look like a strong answer") that a single command disproves.
• All three reproduced a summary document's reasoning without checking it against the code. The summary said a certain value is "never shown as a bare percentage, because two decimal places would be dishonest." The code ships that value at two decimal places. All three repeated the reasoning; none noticed the contradiction.
• Two stated a count their own list contradicted. One wrote "five outcome types", listed four, then referred to a sixth.
• One fabricated a quotation. It put quote marks around a plausible paraphrase of a copy string rather than the string. It also cited a code identifier that does not exist.

These are the failures the rules above exist to prevent. They are not hypothetical.

Structure that makes the rules easy to follow

For anything explaining a problem, a defect, or a decision, three labelled parts keep the context attached:

• Situation. What is actually there. Concrete, checkable, no evaluation yet.
• Problem. What goes wrong because of it, and for whom.
• Resolution. What to do, and what it costs.

For a decision, record the alternative that was rejected and what would reverse the decision. A decision without its rejected alternative reads as the only option anyone considered, which is almost never true.

Red flags

Four of these are detectable by pattern; run the advisory pass over the finished draft and read every line it prints as a place to look, not a verdict:

bash ~/.claude/skills/documentation-create/scripts/prose-flags.sh <file>

Stop and fix when you notice yourself writing:

• A number followed by a plural noun, with no list.
• "The" plus a technical noun, on its first appearance in the document.
• "The most", "the best", "the worst", "the sharpest", with no criterion.
• "-er than" with only one side named.
• Any absolute claim about behaviour ("never", "cannot", "always") that you have not executed.
• Quotation marks around text you did not copy and paste.
• A claim you can trace to a summary document rather than to the thing itself.

Common mistakes

Cutting words instead of adding context. The fix for an unsupported sentence is the support, not a shorter sentence. Removing the flourish and leaving the bare assertion produces something worse: terse and still unsupported.

Verifying the easy claims and asserting the hard ones. The claims worth checking are the ones carrying the argument, not the ones that are easy to look up.

Treating the author's own summary as a source. A post-mortem, a spec, or a decision log is evidence of intent. Check it against the implementation before repeating it.