Doc standards

doc-standards — write documentation that survives translation, retrieval, and skepticism

Documentation written by an LLM has a smell: elegant-variation synonyms, subordinate clauses, filler, hedging. The fix is not "write better" — it is adopting the constraints professional documentation systems already use. This skill stacks five criteria layers, from structure down to the word, and ends in a machine gate.

The five layers

Layer	Question it answers	Source standard
1. Structure	Which document am I writing, for whom?	Diátaxis + ISO 24495
2. Controlled language	Is each sentence unambiguous?	ASD-STE100
3. House style	Is it consistent with developer-docs convention?	Google / Microsoft style guides
4. AI readability	Can an agent retrieve and use each section alone?	llms.txt + retrieval practice
5. Verification	Can a machine confirm 2–4?	Vale / bundled checker

Workflow

1. Structure first (delegate, don't duplicate)

Classify the document before writing a word: tutorial, how-to, reference, or explanation (Diátaxis). Each has a different contract with the reader — a tutorial promises safe success, a reference promises completeness, a how-to promises a working result, an explanation promises understanding. Mixing them is the #1 structural defect.

• Generating new docs or auditing coverage → if a Diátaxis-structure skill is installed (for example gstack's document-generate / document-release), invoke it — it owns the Diátaxis map. Otherwise classify and scaffold the document type yourself before writing. This skill governs the prose inside whatever gets scaffolded.
• Then apply ISO 24495's reader-first gate: state who the reader is and what they must be able to DO after reading. If you cannot name the reader, stop and find out. The four plain-language principles — relevant, findable, understandable, usable — are the acceptance criteria for the whole document, not decoration.

2. Draft under controlled language (ASD-STE100)

Read references/ste100.md before drafting anything longer than a paragraph. The core discipline, always in force even without reading the reference:

• One word, one meaning. Pick one term per concept and repeat it everywhere. Synonym variation ("verify / check / confirm / ensure") is the strongest LLM tell and the #1 source of reader doubt ("is a 'token' the same as the 'key' above?").
• Procedural sentences ≤ 20 words, descriptive ≤ 25. One instruction per sentence.
• Active voice, imperative for instructions. "Run the command", never "the command should be run".
• Simple tenses only. No present perfect ("has been deprecated" → "was deprecated in v2.1").
• Warnings before the step they protect, in command form.

3. House style pass (Google/Microsoft)

Read references/style-guides.md when writing developer-facing docs. Highest-value rules: second person, present tense, sentence-case headings, goal-before-action steps ("To enable X, run:"), descriptive link text, no "simply/just/easy/please", global-audience English (no idioms, no "e.g./i.e."), consistent bold-UI/code-font conventions.

4. AI-readability pass

Read references/ai-readability.md when the docs will be consumed by agents, RAG pipelines, or coding assistants — which in practice is all public docs now (GitBook measures ~41% of doc traffic from agents). Core rule: every heading-delimited section must make sense retrieved alone — no "as mentioned above", no split concepts, full parameter tables, realistic examples with expected output, and an llms.txt index at the docs root.

5. De-slop and gate

• If an AI-tell removal skill is installed (for example stop-slop), run its checklist on the final prose — it owns that layer; don't re-derive its rules here. Without one, sweep for the classic tells: filler openers, "not X but Y" contrasts, adverb padding, pull-quote sentences, em-dash overuse. One precedence rule: where literary rhythm advice ("vary sentence length") conflicts with STE100 uniformity in procedural steps, STE100 wins inside numbered procedures; rhythm wins in explanations.
• Run the machine gate:

python3 <this-skill's-base-directory>/scripts/check_docs.py <file-or-dir> [--max-words 25]

It checks sentence length, passive voice density, banned words, synonym-set collisions, heading hierarchy, section self-containment markers, and relative-link integrity — zero dependencies. If vale is installed and a .vale.ini exists, it defers the style layer to Vale (stronger). To set Vale up for a project, read references/vale-setup.md.

The gate is advisory line-by-line but binding in aggregate: fix every error-level finding; use judgment on warnings (quoted text, proper nouns, and code samples are legitimate exceptions). Do not declare documentation done while the gate reports errors.

Terminology table (do this once per project)

Before the first doc ships, write a terminology table into the project's docs (docs/terminology.md or a section in the README): each concept, its ONE approved term, and the banned synonyms. Every later doc, PR description, and error message uses the approved column. This is the cheapest single intervention — it converts "one word, one meaning" from a per-sentence effort into a lookup.

Example:

Concept	Approved	Banned
API credential	API key	token, secret, credential
Stop a running job	cancel	stop, kill, abort, terminate

When NOT to apply full strictness

• Marketing copy, blog posts, pitch decks — voice matters more than control; use stop-slop alone.
• Code comments — follow the surrounding codebase's comment density and idiom instead.
• Legal text — do not simplify contract language; plain-language rewrites of legal clauses change meaning.