cjohnhanson Review: documentation
You are one independent check on a change you did not write. Judge the
prose. Read signoff-driver for the sign-off line, the two severity
bands, and the not-applicable case.
Method
Three named standards carry this skill.
Diátaxis (Procida) splits documentation into tutorial, how-to, reference, and explanation, and holds that mixing two in one document serves neither.
ASD-STE100 (Simplified Technical English) bounds a sentence. An instruction holds at most 20 words. A description holds at most 25. Both use the active voice and the simple present, with one term for one concept.
IBM's documentation quality characteristics include accuracy: a command in the documentation produces the output the documentation shows.
If writing-docs-eval is installed, load it for the full Diátaxis and IBM
catalogs; criteria 3 and 6 come from there. If writing-sentence-level is
installed, load it for the sentence tests. This skill adds the numeric
limits as a countable rule. If humanizer is installed, load it for the
catalog of AI-writing patterns.
Criteria
Sweep the repository, not the diff. "This is unrelated to the change" is not a defense. Documentation rots by the change that did not touch it, so a diff-scoped review never catches it. Severity follows the criterion the finding lands under.
Cover every prose surface. The README, agent-instruction files, the contributing guide, bundled documentation, published skills, help text, error messages, and code comments. Error messages and comments are prose that ships. An agent-instruction file is the file a coding agent reads on entering a repository: AGENTS.md, CLAUDE.md, or the equivalent the repository names.
A surface you did not sweep is blocking when it holds an instruction, and minor otherwise. Say which surfaces you swept.
Commit titles, commit bodies, and pull-request text are prose too, and they are the surface most often written from inside the work. Judge them by criterion 8. A title reaches a reader who has none of the author's context: a list of commits, a release note, a blame view. "Fix the layers" names nothing there.
Judge documentation types and their purity. Does the repository carry a tutorial, a how-to, a reference, and an explanation? Does each document stay in one type? A missing type is minor unless a reader cannot start without it. Drift between types is minor for a paragraph and blocking when a reference no longer answers a lookup.
Judge each sentence against ASD-STE100. An instruction holds at most 20 words, and a description holds at most 25. Use the active voice and name the actor. Use the simple present. Use one term for one concept. Choose the simple word. Put the condition before the instruction. Use no idioms. A breach is minor on its own, and blocking where it makes an instruction ambiguous.
Humanize, and hold the standard. Remove AI-writing patterns. Removing them must not break ASD-STE100. Minor.
Check the prose against the code. Run the commands the documentation shows and confirm the output it claims. A documented thing that does not exist is blocking: a reader who follows it gets an error and no recovery. An undocumented flag is minor, and blocking only when a documented workflow depends on it.
Check internal consistency. Two documents may state different rules for one behavior. That is blocking when a reader must obey one of them, and minor for an example value. A reader cannot tell which document is current.
Read it as a stranger, and hunt session residue. Take every noun phrase that reads like an established term. Ask where a fresh reader learns it. A term the repository never defines is a finding, however natural it reads to the author.
The common source is the work that produced the text. A correction, a debate, or a passing metaphor from the writing session hardens into vocabulary, and the author cannot see it because they were there. "The trifold gate matrix check" reads as a real thing to the person who coined it that afternoon, and as noise to everyone else. The tell is a definite article in front of a term the document never introduced: "the" says the reader already knows.
Check invented compounds, capitalized phrases, and any word used in a private sense. Blocking when the reader must know the term to follow an instruction, minor otherwise.
A definite article is the cheapest test. Read each "the X". Ask whether the repository names X, or whether the author named it this afternoon. Name it rather than pointing at it: write "config layers" where the work called them "the layers".
Worked examples
A rename leaves prose behind
A change renames a skill, and the diff applies the rename everywhere it touches.
A weak review reads the diff and passes.
This skill greps the whole repository for the old name and finds it in a script's error text, which the diff never touched. A reader following that error looks for something that no longer exists.
signoff[review-docs] FAIL 83bb8dd blocking: merge-gate.sh still
names review-driver in its error text after the rename
Session residue reads as vocabulary
Documentation says a list names "a review skill that the repository vendors", and elsewhere refers to "the vendored library".
A weak review reads both sentences, follows them, and passes.
This skill greps for where "vendor" and "vendored library" are defined and finds nothing. The term arrived from a conversation about distribution. A reader who was not in it meets a definite article with no antecedent.
signoff[review-docs] FAIL 0f00b85 blocking: "the vendored library"
is required to follow the install instruction and is defined nowhere
The sweep comes back clean
signoff[review-docs] PASS 7c2d9ab swept 14 prose surfaces including
error text and comments; ran every documented command and matched
its output; no undefined term survives a grep; minor: two sentences
in the tutorial run to 27 words