Claude Cursor Skill

docs-writing

Write, restructure, or review documentation — tutorials, how-to guides, reference pages, concept/explanation docs, API references, READMEs, changelogs, release notes, and troubleshooting guides. Distills documentation craft from Mintlify's guides (compiled from technical writers

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download skmtc-skmtc-deno_docs_skills_docs-writing-e3abffc.zip · 28 KB
skmtc/skmtc 19 0 forks Apache-2.0 Updated 7d ago
Part of skmtc/skmtc — 12 skills

Install

skills CLI npx skills add https://github.com/skmtc/skmtc/tree/main/deno/docs/skills/docs-writing
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install skmtc-skmtc@llmmart
Git git clone https://github.com/skmtc/skmtc.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole skmtc/skmtc collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Writing documentation

Documentation craft distilled for the moment of writing. The core stance: people don't read docs for fun; they arrive with a goal — and they read at most ~20–28% of the words on a page (NN/g). Every rule below serves getting the reader from arrival to accomplished goal with minimum friction — and the same properties that serve a skimming human serve an AI agent reading the page.

Companion files, read on demand:

  • templates.md — page skeletons + quality bars for how-to, tutorial, reference, concept, README, changelog, release notes, and troubleshooting pages.
  • mechanics.md — mechanical enforcement (Vale, markdownlint, link checking, testing code examples) and the llms.txt format.

1. The seven principles that override default writing intuitions

Writing docs is not writing prose. These override what generic "good writing" instincts would suggest:

  1. Verify before you document. Never document behavior you haven't executed, observed, or read in the source. LLM-written docs fail here in characteristic ways: plausible flags that don't exist, documented intent instead of actual behavior, invented defaults, hedged claims papering over unchecked ones. If you can't run it, read the code that implements it; if you can do neither, mark the claim unverified rather than asserting it. This is the docs analogue of skmtc-debug's verify-first stance.

  2. One page, one content type, one persona. Decide before drafting whether the page is a tutorial, how-to, reference, or explanation (§3), and who it's for (§2). "Writing for multiple audiences leads to compromises that satisfy no one." A page that teaches AND exhaustively catalogs AND justifies design does none of them well.

  3. Lead with the answer, not the context. Readers scan in an F-pattern and abandon pages whose opening doesn't confirm what the title promised. Put the outcome or instruction in the first paragraph; front-load the information-carrying words in headings. A reader should be able to leave after the first paragraph having gotten what they came for.

  4. The curse of knowledge is the default failure mode. You know how everything works; the reader doesn't. State prerequisites explicitly, define acronyms on first use, never assume internal conventions (naming schemes, auth flows, team shorthand) are known. Validate against real evidence — support tickets, friction logs, user questions — not assumptions. Test: could someone who joined yesterday follow this?

  5. Every page is page one. Readers arrive from search engines, deep links, and AI retrieval — never at your table of contents. Each page must establish its own context (what it covers, who it's for, what it assumes) in its opening. Reading-order dependencies ("as mentioned above", "in the previous section") are forbidden; link to supporting material instead.

  6. Code examples are load-bearing, not decorative. Many readers only read the code blocks. Every example must be complete and runnable as-copied — imports, setup, the call, response handling. "A code example is worth a thousand words."

  7. Wrong docs are worse than no docs. "Consider incorrect documentation to be worse than missing documentation" (Write the Docs). Outdated or misleading content wastes users' time and erodes trust in the whole product. When you can't maintain a page, delete it — removal often serves users better than retention.

2. Know your audience

Center the reader's goal, not the product's feature list.

The four personas

Persona Needs Serve with
Technical decision maker Evaluate fit and architecture Overviews, concept docs, comparison-friendly framing
New end user Get to first success fast Getting-started tutorial, quickstart
Integrating developer Implement correctly How-tos, reference, complete examples
AI agent / LLM Retrieve and act without inference Structure, explicit prerequisites, self-contained sections, unambiguous terminology

Pick one primary persona per page. The AI-agent persona is served by the same properties that serve skimming humans — clear headings, semantic markup, defined terms, runnable examples — so it rarely needs separate pages, but it does raise the bar on explicitness (§6).

Defeating the curse of knowledge

  • Talk to users (or their proxies: support, UX research, product). Harvest the terminology they actually use — it often differs from internal naming, and it's what they'll search for.
  • Keep a friction log: use the product as a new user would and record every step — expected vs. actual, every confusion, workaround, and surprise. Each entry is either a docs fix or a product bug; file it as one or the other. (This ecosystem already runs one at docs/friction-log/.)
  • Use the five W's to define a page's scope before writing: who is this for, what will they accomplish, why would they need it, where/when does it apply — then how.
  • Embed with support: recurring tickets are a ranked list of doc gaps.
  • Test docs by asking an AI assistant product questions and seeing whether the docs let it answer correctly — a cheap proxy for "does the page carry its own context".
  • Assume the reader is qualified for the page's task; don't explain basics inline. Give unqualified readers enough context to recognize they're on the wrong page, plus a link to where they can qualify themselves — a page "can't bring every possible reader up to speed without becoming a textbook."
  • Don't over-document niche edge cases in guides; route those to community channels and keep guides focused on majority paths. (Reference is different — see §3: exhaustive within its scope.)

3. Content types (Diátaxis)

Four types, distinguished by what the reader is trying to do. Assign each page exactly one type before drafting.

Type Reader's goal Reader's mode Structure Voice
Tutorial "Teach me by doing" Study Linear steps, guaranteed outcome Guiding: "we", first person plural
How-to guide "Solve my specific problem" Work Problem → solution steps, may branch Direct, conditional imperatives
Reference "Give me the precise fact" Work Scannable catalog, consistent format Neutral, terse, austere
Explanation "Help me understand why" Study Discursive, conceptual Reflective, comparative

The compass — when the type is unclear

Ask two questions about the content (works at page, section, or sentence level):

  1. Does it inform action (doing) or cognition (thinking)?
  2. Does it serve acquisition of skill (study) or application of skill (work)?

action + acquisition → tutorial · action + application → how-to · cognition + application → reference · cognition + acquisition → explanation.

Type is function, not difficulty. An advanced course is still a tutorial (a lesson, safely in the instructor's hands); a trivial one-step procedure is still a how-to (a worker's task). "Beginner content = tutorial, advanced content = how-to" is Diátaxis's most common and most harmful misreading — classify by study-vs-work, never by difficulty.

Navigation should mirror the split: Getting Started → Guides → Reference → Concepts. The SKMTC docs tree instantiates this as using/tutorials/ + using/how-to/ + using/recipes/, authoring/ (same trio), reference/, and concepts/ + explanation/. Recipes are how-to guides in recipe form — the recipe is Diátaxis's own model for the type (assumes competence, answers one specific question, no teaching). The four types classify needs, not directory names; a section may be named anything so long as each page serves one need well.

Writing rules per type

Tutorials — learning-oriented:

  • Open by stating exactly what the reader will have built/achieved at the end.
  • First person plural, teacher's voice: "In this tutorial, we will…"; unambiguous imperatives: "First, do x. Now, do y."
  • Every step delivers a visible result, and the text names it: "The output should look something like…" — checkpoints let readers self-verify they're on track.
  • Small incremental steps; a tutorial "doesn't offer choices or alternatives" — one carefully-managed path.
  • Teach through experience, not explanation — link to explanation docs rather than digressing: "We must do x before y because… (see [explanation] for details)."
  • Must work every time: "so well constructed that things can't go wrong" — a tutorial that fails at step 4 loses the user, possibly permanently. Expect high maintenance cost as the product evolves.

How-to guides — task-oriented:

  • Title is the task in the user's words ("Skip operations for one generator"), not the feature's name.
  • Conditional imperatives carry the branching: "If you want x, do y. To achieve w, do z." (Tutorials never branch; how-tos usually do.)
  • About goals, not machinery: address the real-world task, not a walkthrough of the tool's controls.
  • Assume foundational knowledge; state the specific prerequisites, then skip the obvious steps.
  • "Practical usability is more helpful than completeness" — only the context necessary for this task; offload option inventories to reference: "Refer to the x reference for a full list."

Reference — information-oriented:

  • "Austere and uncompromising": describe, and only describe. Neutral statement of fact; no instruction, no rationale.
  • Structure mirrors the product's structure, and entry order mirrors the source of truth, so drift is visible.
  • Maximize scannability: tables, identical per-entry format, parallel phrasing, one naming convention across every entry.
  • Copy-paste-ready examples per entry (examples illustrate without explaining — they're welcome); required vs. optional marked explicitly; constraints and defaults stated, not just the name restated.
  • Exhaustive within its declared scope — a reference that omits entries is broken in a way a how-to never is.

Explanations — understanding-oriented:

  • The "About" test: an explanation title should tolerate an implicit "About …" prefix ("About user authentication"). If it can't, the page probably isn't explanation.
  • Cover design decisions, constraints, and the alternatives that were rejected (and why).
  • Opinion is allowed and required here: explanation "can and must consider alternatives, counter-examples or multiple different approaches."
  • Explanation "tends to absorb other things" — expel instruction and technical description to their proper homes.

Type-mixing smells

  • A tutorial that pauses for three paragraphs of rationale → move the rationale to an explanation doc, link it.
  • A tutorial offering choices ("you could also use…") → cut; one path.
  • A reference entry with step-by-step setup → extract a how-to.
  • A how-to that exhaustively lists every option → extract reference material, keep only the options the task needs.
  • A how-to that keeps stopping to teach → trust the reader's competence; link the tutorial instead.
  • Time-sensitive content (release notes, announcements) in evergreen docs → belongs in a changelog or blog (see templates.md).

Scoped exception — API reference surfaces. Reference pages for an HTTP API may deliberately blend the catalog with per-language samples, request/response pairs, and short usage notes (the Stripe pattern, §8). That blend is confined to the API reference surface; docs-tree pages keep one type each.

Applying Diátaxis incrementally

Don't restructure top-down into four empty boxes and shovel content in — "Diátaxis changes the structure of your documentation from the inside." The loop: choose something small; assess what user need it serves and how well; decide on a single next action; do it and publish immediately. Documentation is never finished — but at every moment it can be complete: useful, correct, and coherent at its current scope. Never hold back an improvement waiting for "done".

4. Style and tone

  • Cut ruthlessly — within a section. Every unnecessary word taxes a reader who is there to get something done. But brevity governs sentences and paragraphs; explicitness governs boundaries: restating context at a page or section opening is not filler — it's the entry point for a reader (or retrieval chunk) landing there (§1.5). Cut words, not context.
  • Active voice, imperative mood. "Create a file", not "a file should be created".
  • Second person. "You" — the doc serves the reader's task. (Exception: tutorials use "we" — §3.)
  • Short paragraphs (2–4 sentences), meaningful headings, lists for enumerable things, tables for structured facts.
  • One term per concept, everywhere. "API key" and "API token" used interchangeably reads as two different things. Pick one; grep for the other (enforceable with a Vale consistency rule — mechanics.md).
  • Don't narrate the obvious. "Click Save to save" is negative value. Document what isn't intuitive.
  • Spelling and grammar are trust signals. Errors in the docs read as errors in the product.

Word-level rules (bad → good)

The high-leverage subset of the Google and Microsoft style guides — rules a fluent writer (or LLM) gets wrong by default:

  • Delete "simply", "easily", "just", "obviously", "of course". What's easy for the writer isn't for the reader; the sentence survives without them. "Simply run the installer" → "Run the installer."
  • No "please" in instructions. "Please click Save" → "Click Save."
  • Present tense for product behavior; never "will" or "would". "The server will send an acknowledgment" → "The server sends an acknowledgment."
  • Timeless docs: ban "currently", "new", "now", "soon", "as of this writing", "latest", "old", "eventually". "The emulator now supports filters" → "The emulator supports filters." If "new" is unavoidable, anchor it to a date. Exception: changelogs and release notes.
  • No anthropomorphism. Software doesn't want, think, see, know, or care. "The PC sees a new device" → "The PC detects a new device."
  • "may" = permission only; "might" = possibility; "can" = ability. "The call may fail" → "The call might fail."
  • "should" is ambiguous — use "must" for requirements; rewrite recommendations as "we recommend" or a direct imperative.
  • Spell out Latin abbreviations: "e.g." → "for example", "i.e." → "that is"; avoid "etc." (finish the list or use "such as").
  • "allows you to" / "enables you to" → "lets you" — or make the reader the subject: "The API allows you to filter results" → "Filter results with…".
  • "in order to" → "to"; "utilize"/"leverage" → "use".
  • Start instructions with the verb — kill "You can…" and "There is/are…" openers. "You can access the settings from…" → "Open the settings from…".
  • Sentence-style capitalization for all headings. Never Title Case. Oxford comma always. Contractions are fine.
  • "select" for UI interaction (not "click"/"tap" — accurate for keyboard, touch, and assistive tech); select/clear checkboxes (never "check"/"uncheck").
  • Never inflect code identifiers — attach a noun and inflect that: "Nodes" → "Node objects"; "ADDRESS's value" → "the ADDRESS constant's value".
  • Inclusive defaults: allowlist/blocklist, primary/replica, placeholder (not dummy), "stops responding" (not hangs), singular "they" (never "he/she").

Writing for a global audience

Docs are read by non-native speakers and machine translation:

  • Short sentences, one idea each; no more than two clauses chained with and/or/but.
  • Keep optional function words — "Verify all tables migrated" → "Verify that all tables were migrated."
  • Avoid ambiguous connectives: "once" → "after"/"when"; "while" → "although"/"during"; "since"/"as" → "because" (unless temporal).
  • Place "only" immediately before the word it modifies: "Only request one token" → "Request only one token."
  • No noun stacks (max two nouns as modifiers), no phrasal verbs where a single verb exists, no idioms, colloquialisms, humor, or culture-bound references.
  • Dates: spell out the month ("January 19, 2026") or ISO 8601 (2026-01-19); never 04/15/17; never seasons.

Lean on the Google or Microsoft style guide for the long tail; automate enforcement with Vale in CI (mechanics.md) rather than relitigating style in review.

5. Writing procedures

Step sequences have their own mechanics (Google/Microsoft procedure rules):

  • Numbered list; one action per step. Combine actions only when they're trivial and happen in the same place.
  • Location and purpose before action: "In Google Docs, select File > New" — not "Select File > New in Google Docs". "To start a new run, click…" — the goal first, so the reader can skip steps they don't need.
  • State a step's result in the same paragraph as the action, after it — not as its own numbered step: "Drag the tiles to an open space. When a gray bar appears, release them."
  • A single-step procedure is one bullet, not "1.".
  • Optional steps start with "Optional:".
  • End with the completing action — the Save/Apply step; don't leave the procedure hanging. If the end state isn't obvious, say what success looks like.
  • Menu paths: bold items separated by ">" (File > New > Document); use one convention throughout, and only when every hop uses the same interaction.
  • One method per procedure. Alternatives and keyboard shortcuts belong in a reference table, not woven into the steps.
  • Task-phrased, parallel headings ("Create a profile", "Add an account"); don't follow the heading with a sentence that repeats it.

6. Structure for humans AND AI agents

The same page properties serve skimming humans, search engines, and LLM retrieval. Optimize once:

  • Establish context in the opening: what the page is about, who it's for, where it fits — position in the nav tree doesn't travel with the page into a search result or a retrieval chunk.
  • Descriptive headings with honest information scent. Readers choose links and sections by an estimate of what's behind them — from the label alone. "Rate limiting" beats "Keeping things under control"; phrase task headings the way a user would ask ("Rotate an API key"). A heading should answer "is my answer in this section?" without reading the section. Over-promising titles get the page abandoned and burn trust.
  • Semantic markup: proper heading hierarchy (H2 → H3 → H4, no skipped levels), lists for enumerations, tables for structured data (headers in the first row only, no merged cells), fenced code blocks with language tags.
  • Explicit prerequisites at the top of task pages — humans skip them at their own risk; AI agents cannot infer unstated context.
  • Definitions before edge cases; common cases before advanced.
  • Stay on one level. Don't oscillate between high-level principle and low-level detail on one page; link up to concepts and down to reference and let the reader change levels when they choose.
  • Link richly, along subject affinity — every page is a hub. Descriptive anchors ("see the enrichments reference"), never "click here"; no positional language ("above"/"below" → name the section or link it).
  • Self-contained sections: a section pulled out of the page by a retrieval system should still make sense. Restate the subject noun (not "it"); restate (briefly) rather than relying on "as mentioned above".
  • Conform to type: pages with the same purpose share the same sections in the same order (templates.md) — predictability serves scanners, and a defined shape makes gaps visible.
  • Document error scenarios and deprecations explicitly — error strings are among the highest-value search and retrieval targets, and the least often documented.
  • Delete or clearly mark outdated content: AI retrieval surfaces deprecated pages with no sense of staleness.
  • Ship the machine surface: an /llms.txt index (and llms-full.txt if the corpus fits a context window) — format and rules in mechanics.md.

Validating the structure

  • Analytics: where do readers enter, what do they search for ( especially searches with zero results), where do they exit.
  • Session paths: do readers follow the navigation you designed, or fight it?
  • Direct tests: watch a user (or a new hire — an excellent proxy) try to answer a specific question using only the docs.
  • Common pitfalls: overloaded top-level categories (seven items is a comfortable limit for an unordered list), essential pages buried three levels deep, section labels only insiders understand.

7. Code examples

The most-read part of any developer doc. Standards:

  • Runnable as-copied. Full workflow: imports, setup, authentication placeholder, the call, response handling. A fragment that needs unstated scaffolding is a support ticket.
  • Realistic data — not foo/bar; use values shaped like real usage so readers can map the example onto their case.
  • Placeholders in UPPER_SNAKE_CASE, followed by "Replace the following:" with one line per placeholder in order of appearance.
  • Show the expected output/response alongside the request, so readers can verify success without guessing.
  • Include error handling in longer examples — it's where real integrations spend their time.
  • Multiple languages via tabs where the audience spans ecosystems; every tab's example kept equivalent.
  • Test examples in CI. A fenced code block is a claim; untested claims rot, and an example that rots is worse than none (§1.7). Extraction and doc-testing patterns per ecosystem are in mechanics.md; mark deliberately non-runnable fragments so the untagged default stays "this must run".

8. API documentation

The specialized high-stakes case. Structure around the developer's journey, and measure it by time-to-first-successful-call.

Required components

Component Bar to clear
Getting started Working integration inside ~15 minutes; never buried
Authentication Step-by-step credential setup, token placement, expiry and rate limits, per-method examples (curl + SDKs)
API reference Complete request/response cycles — paths, methods, parameters, schemas, status codes — not a bare endpoint list
Guides Organized by real tasks ("Send a message", "Accept a payment"), not by endpoint inventory
Error catalog Every error code with context and the remediation, including near-miss distinctions (400 vs 422)
Changelog Timestamped, discoverable, flags breaking changes and deprecations loudly (templates.md for the format)

Practices that separate the best API docs

  • Pair generated reference with authored guides. Auto-generation from an OpenAPI spec is a starting point only — it has no editorial judgment, no use-case coverage, no workflow ordering. Layer opinionated guides on top; never ship the generated reference alone.
  • Workflow-first organization (the Stripe pattern): each reference page carries descriptive titles, per-language samples, realistic request/response pairs, and usage notes. This is the sanctioned type-blend — scoped to the API reference surface (§3).
  • Copy-paste-ready everywhere, ideally with the reader's own test credentials injected when docs are behind a logged-in state — but never require login to read the docs; gated docs kill self-service evaluation.
  • Skimmable and searchable: developers arrive with a task, not to read linearly.
  • Interactive playgrounds on reference pages turn specs into executable experiences.
  • Design for LLM consumption: consistent formatting and rich examples let AI assistants generate correct integration code from your docs — an adoption channel in its own right.

9. Page templates

templates.md holds compressed skeletons — ordered sections, a one-line note per section, and the 2–3 quality criteria separating a good instance from a mediocre one — for:

how-to guide · tutorial · reference entry · concept/explanation · README · changelog (Keep a Changelog format) · release notes · troubleshooting guide

Use them as the "conform to type" baseline (§6): start from the skeleton, delete sections that genuinely don't apply, and keep the order. Two worth internalizing:

  • README = cognitive funnel, not manual. Broadest first — what it is (< 120 chars), who it's for, a runnable usage example — so the reader can bail out at any depth having lost minimal time. Depth belongs in the docs tree; the README links there. License last.
  • Changelogs are for humans, not machines. Never paste git log. Group by Added/Changed/Deprecated/Removed/Fixed/Security, newest first, ISO dates, an [Unreleased] section at the top, and always announce deprecations one version before removal — selective entries "can be as dangerous as not having a changelog".

10. Media

Media is supplementary. If the workflow is clear in text alone, don't add visuals — every asset is a maintenance liability that silently rots when the UI changes. Screenshots for UI elements that are hard to describe; diagrams as code (Mermaid — text-diffable) over image exports; video only for long procedures, and only with captions. Non-negotiable: alt text on images (descriptive and specific — "OAuth 2.0 flow", not "diagram"), and never present information only in an image — it's invisible to screen readers, search, and AI retrieval alike.

11. Discoverability (SEO and AEO)

Most readers arrive from a search engine or an AI assistant, not your nav. Answer Engine Optimization is §6 done well — there is no separate trick: literal headings, self-contained sections, defined terms, stated prerequisites, complete examples, documented errors and deprecations, loud deprecation markers. The classic mechanical layer still applies: titles ~50–60 characters and meta descriptions ~150–160 frontloading the terms users actually search (harvested from user language, §2); descriptive link anchors; compressed images; a current sitemap. Skip structured-data gymnastics unless you have evidence your audience arrives through them.

12. Maintenance

Docs rot by default; only a system prevents it.

  • Docs-as-code: docs live in git, change via PRs, deploy automatically, version alongside the code they describe. Review catches errors before publication and lets engineers contribute through tools they already use.
  • ARID, not DRY — "Accept (some) Repetition In Documentation." Docs are read in fragments, so they can't be as DRY as code: single-source what you can, duplicate deliberately where the reader needs it in place — and give every duplicated fact one designated canonical home so drift is detectable (this ecosystem's selective-duplication policy in docs/skills/README.md is this principle applied).
  • Couple docs to shipping: a user-facing change isn't done until its docs are updated — enforce in the definition of done or PR template, and automate detection of drift (e.g. flag when the OpenAPI spec changes but the guide didn't).
  • Automate the boring checks: broken links, heading hierarchy, missing alt text, filler words, terminology consistency, example compilation — the full toolbox with configs is in mechanics.md.
  • Edit in sequenced passes, one concern each — drafting and editing are different acts; never do both at once. The order: (1) technical accuracy — do the instructions produce the promised result; (2) completeness — can the reader succeed with what's here; (3) structure — do headings and prerequisites guide the reader; (4) clarity and brevity — cut. Self-review with the §13 checklist first, then peer review with a specific ask, then expert technical review for complex topics.
  • Prioritize by impact, not schedule: the 10 most-viewed pages get disproportionate attention. Use the traffic × rating grid: high-traffic/low-rating pages are the urgent queue; low-traffic/ high-rating pages hold patterns worth replicating.
  • Assign ownership. Documentation without a named owner diffuses into no one's job and quietly dies.
  • Deprecate before deleting: mark the content deprecated in place, point to the replacement, give notice — then delete what no longer serves users (§1.7).

13. Measuring success

Numbers require interpretation — "don't fall into the trap that a bigger number means better performance."

Signal Reading it honestly
Page views Interest — or bots, or a product bug driving people to the docs
Time on page Engagement — or frustration hunting for an answer
Zero-result searches Direct gap list; the highest-signal analytic
Thumbs-up ratio Target ~75%+; below that, the page misleads or misses
Support ticket volume on documented topics The docs' business case: each deflected ticket is the win
AI-assistant query logs What users actually ask, in their words — feeds §2

Compare against your own baseline over time, not absolute thresholds. Tie the program to business outcomes: onboarding speed, support deflection, retention.

14. Pre-publish checklist

Before a page ships:

  • Every behavioral claim verified — executed, observed, or read in source; anything unverifiable is marked, not asserted (§1.1)
  • One content type, chosen via the compass if unclear; no type-mixing smells (§3)
  • One primary persona; prerequisites stated at the top
  • The answer/outcome appears in the first paragraph; the opening establishes context for a reader arriving from search
  • Headings are descriptive, front-load key terms, and don't skip levels
  • Every code example runs as-copied and shows expected output; non-runnable fragments are marked
  • Terminology consistent — grep for known synonyms of key terms
  • No filler (simply|easily|just|obviously), no time-bound words (currently|new|soon) outside release notes, present tense for product behavior (§4)
  • Procedures follow §5: one action per step, location before action, results stated, completing action present
  • Page conforms to its type's skeleton (templates.md)
  • Errors and edge cases the reader will hit are documented
  • Links have descriptive anchors and resolve; no positional language
  • Images have alt text; media passes the "necessary?" test (§10)
  • Title/description frontload searchable terms
  • The page has an owner and a reason to exist that analytics could later confirm

15. Task cards

Card: Documenting a new feature

  1. Identify the persona and their goal (§2). Write the five W's.
  2. Verify the behavior first (§1.1): run the feature, note the actual commands, flags, outputs, and failure modes — this raw material is the draft's skeleton and its fact-check.
  3. Split the material by type (§3): quickstart steps → tutorial or how-to; option/flag inventory → reference; design rationale → explanation. Resist the single mega-page.
  4. Outline first — every step the reader needs, then reorder to the reader's flow. Draft the how-to first (it forces the user-goal framing) from its templates.md skeleton, then extract reference entries, then backfill explanation.
  5. Write and run every code example.
  6. Edit in passes — accuracy, completeness, structure, brevity (§12) — then run the §14 checklist; place pages in the tree by type.

Card: Reviewing/auditing an existing page

  1. Determine its intended type (use the compass, §3) and persona. If undeclarable, that's finding #1.
  2. Check the opening: does it establish context and state what the page delivers?
  3. Run examples. Diff terminology against the rest of the docs.
  4. Check staleness against the product's current behavior — wrong content is the highest-severity finding (§1.7).
  5. Grep for the mechanical smells: filler words, time-bound words, "click here", skipped heading levels (§14).
  6. Verdict per finding: fix, split (type-mixing), or delete.

Card: Standing up docs for a new project

  1. Skeleton by type: Getting Started → How-to Guides → Reference → Concepts (§3), pages from templates.md.
  2. Write the getting-started path first and make it bulletproof — working result in ≤15 minutes.
  3. Reference next (breadth), explanations last (depth).
  4. Wire the maintenance system before content grows: docs-as-code, link checking, prose lint, docs-updated-with-change policy, and the machine surface (llms.txt) — configs in mechanics.md.
  5. Thereafter improve incrementally (§3): one small published step at a time; never a big-bang restructure.

16. Sources

Distilled July 2026 from:

  • Mintlify Guides — https://mintlify.com/guides/introduction (know-your-audience, content-types, writing-style-tips, navigation, media, seo, maintenance, success), itself compiled from interviews with technical writers at Stripe, Amplitude, Anaconda, and GitHub; plus Mintlify's API-documentation recommendations and developer-docs blog posts
  • Diátaxis framework — https://diataxis.fr (the four types, the compass, tutorials-vs-how-to, complex hierarchies, per-type language guidance, quality; Daniele Procida)
  • Google developer documentation style guide — https://developers.google.com/style (word list, tense, anthropomorphism, timeless documentation, procedures, link text, accessibility, translation)
  • Microsoft Writing Style Guide — https://learn.microsoft.com/en-us/style-guide/ (top 10 tips, bias-free communication, global communications, step-by-step instructions)
  • Every Page Is Page One — Mark Baker (the seven characteristics of EPPO topics; information foraging) — https://everypageispageone.com
  • Write the Docs — https://www.writethedocs.org/guide/ (docs principles incl. ARID, docs-as-code, style guides)
  • Docs for Developers (Bhatti, Corleissen, Lambourne, Nunez, Waterhouse) — https://docsfordevelopers.com (friction log, drafting process, editing passes, content taxonomy)
  • Nielsen Norman Group — how little users read, the F-shaped pattern, information scent — https://www.nngroup.com/articles/
  • The Good Docs Project templates — https://thegooddocsproject.dev (via templates.md)
  • Keep a Changelog 1.1.0 — https://keepachangelog.com (via templates.md)
  • Art of README + standard-readme (via templates.md)
  • llms.txt spec — https://llmstxt.org; Vale — https://vale.sh; markdownlint; lychee (via mechanics.md)
Files (skmtc)
  • design.md 14.4 KB 
    # docs-writing skill — design document

## Purpose

A craft skill: how to write good documentation, loaded at the moment of writing
or reviewing any docs page. Unlike the `skmtc-*` skills it is not SKMTC-specific
— the content is general documentation craft — but it lives in this ecosystem
because the SKMTC docs tree is its primary application surface, and because the
docs tree already instantiates the skill's central framework (Diátaxis) in its
directory layout (`using/tutorials/`, `using/how-to/`, `using/recipes/`,
`reference/`, `concepts/`, `explanation/`).

## Artifact layout (v0.2.0)

- `SKILL.md` — the operational core, loaded on invocation: the seven principles,
  audience, Diátaxis (+ compass), style and word rules, procedures, structure,
  code examples, API docs, maintenance, checklist, task cards.
- `templates.md` — page skeletons + quality bars for eight page types; read on
  demand when drafting a page of that type.
- `mechanics.md` — the automatable subset (Vale, markdownlint, lychee,
  doc-testing) and the llms.txt format; read when wiring CI or the machine
  surface, not when writing prose.

The split follows the ecosystem's skills-push/docs-pull model: material needed
at the moment of writing stays in SKILL.md; material needed when setting up
checks or starting a specific page type moves to companions.

## Content sources

v0.1.0 was distilled July 2026 from Mintlify's published documentation-craft
material (itself compiled from interviews with technical writers at Stripe,
Amplitude, Anaconda, GitHub) plus the Diátaxis four-type model. v0.2.0
diversified the source base to correct the single-vendor emphasis.

| Section                         | Source                                                                                                                                                                                                                                                                                                                  |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| §1 Seven principles             | §1.1 original (verify-first, the agent-as-writer stance, mirroring `skmtc-debug`); §1.2 Mintlify; §1.3 Mintlify + NN/g (F-pattern, ~20% reading); §1.4 Mintlify + Docs for Developers (validation); §1.5 Every Page Is Page One (Baker); §1.6 Mintlify; §1.7 Mintlify + Write the Docs ("incorrect worse than missing") |
| §2 Know your audience           | Mintlify `know-your-audience` + five W's; friction log from Docs for Developers; "assume the reader is qualified" from EPPO                                                                                                                                                                                             |
| §3 Content types                | diataxis.fr in depth: the compass, tutorials-vs-how-to (type ≠ difficulty), per-type voice ("we", conditional imperatives, the "About" test), complex-hierarchies (recipes ruling), incremental application, "always complete never finished" (Procida)                                                                 |
| §4 Style and tone               | Mintlify `writing-style-tips`; word-level rules from the Google style guide (word list, tense, anthropomorphism, timeless docs) + Microsoft (top 10 tips, bias-free, global comms); brevity/explicitness scoping rule original (see decision log)                                                                       |
| §5 Procedures                   | Google `procedures` + Microsoft step-by-step instructions                                                                                                                                                                                                                                                               |
| §6 Structure                    | Mintlify `navigation`/`seo` + EPPO (context, one level, link richly, conform to type) + NN/g information scent                                                                                                                                                                                                          |
| §7 Code examples                | Mintlify + Google placeholder conventions; testing pointer to mechanics.md                                                                                                                                                                                                                                              |
| §8 API documentation            | Mintlify API-docs recommendations (components table, Stripe/Twilio exemplars, time-to-first-call)                                                                                                                                                                                                                       |
| §9 Templates pointer            | templates.md: Good Docs Project, Keep a Changelog 1.1.0, Art of README, standard-readme                                                                                                                                                                                                                                 |
| §10 Media                       | Mintlify `media`, compressed                                                                                                                                                                                                                                                                                            |
| §11 Discoverability             | Mintlify `seo`, compressed; AEO = §6 framing retained                                                                                                                                                                                                                                                                   |
| §12 Maintenance                 | Mintlify `maintenance` + WTD ARID + Docs for Developers (editing passes, deprecate-before-delete, ownership)                                                                                                                                                                                                            |
| §13 Measuring success           | Mintlify `success` + traffic × rating grid                                                                                                                                                                                                                                                                              |
| §14–15 Checklist and task cards | Original synthesis in the house skill style; updated for verify-first, compass, templates, editing passes                                                                                                                                                                                                               |
| mechanics.md                    | vale.sh docs + errata-ai packages; markdownlint; lychee; GitLab docs pipeline; pytest-examples/MDX/mdbook; llmstxt.org + adoption reporting                                                                                                                                                                             |
| templates.md                    | Good Docs Project template repo (how-to, tutorial, reference, concept, README, changelog, release notes, troubleshooting); Keep a Changelog 1.1.0; Art of README; standard-readme spec                                                                                                                                  |

## Decision log — contested seams

Where credible sources disagree, the skill encodes one side rather than
presenting options (a skill offering "A or B" just re-litigates the choice every
invocation). Each entry records the tension, the chosen side, and why — so
future maintainers don't "fix" a decision without knowing it was one.

1. **Diátaxis type purity vs. Stripe-style blended pages.** Both work; mixed
   per-page adoption nullifies both. Chosen: purity governs the docs tree (type
   declared by directory); the workflow-blend is a _scoped carve-out_ for API
   reference surfaces only (§3 smells + §8). Rationale: the tree is already
   committed to type-per-directory, and the carve-out matches how the pattern is
   actually used by its exemplars.
2. **"Cut ruthlessly" vs. "restate context" (brevity vs. explicitness).**
   Chosen: a scoping rule — brevity governs within a sentence/paragraph;
   explicitness governs page and section _boundaries_ (openings, prerequisites,
   restated subjects), since boundaries are retrieval/entry points (EPPO + AEO).
   "Cut words, not context." (§4 first bullet.)
3. **Exhaustive reference vs. don't document niche edge cases.** Chosen: scoped
   by type — exhaustiveness is a property of reference _within its declared
   scope_; edge-case triage applies to guides (§2 last bullet, §3 reference
   rules).
4. **"click" (Google) vs. "select" (Microsoft).** Chosen: select —
   input-neutral, accurate for keyboard/touch/assistive tech, no per-device
   forking (§4 word rules).
5. **Menu-path separator bolding (Google bolds the whole path; Microsoft doesn't
   bold ">").** Chosen: bold items with ">" separators, one convention
   throughout — consistency matters more than the variant (§5).
6. **DRY vs. duplication.** Chosen: ARID with designated canonical homes (§12),
   which is also the ecosystem's existing selective-duplication policy — a
   synthesis with a drift-check mechanism, not an average.
7. **Voice register (Microsoft's marketing-brisk vs. Google's
   restrained-conversational).** Chosen: Google's restraint — developers read
   docs under stress; contractions yes, chirpiness no.
8. **Recipes vs. the four types.** Resolved, not contested: diataxis.fr itself
   names the recipe as the model how-to form and says the four types classify
   needs, not directory names (§3).

## Content boundaries

**In scope:** the craft of a docs page — audience, type selection, style,
structure, examples, media, discoverability, maintenance process, metrics — plus
page templates and the mechanical enforcement toolbox as companions. Applies to
any project's docs.

**Out of scope, deliberately:**

- _Where SKMTC content goes_ (skill vs `llms.md` vs docs tree, the
  selective-duplication policy, canonical homes) — owned by
  `docs/skills/README.md`. The SKILL.md description points there.
- _Writing SKILL.md files themselves_ — skills are an operational artifact with
  their own conventions (frontmatter, trigger phrases, anti-pattern tables); a
  future `skill-authoring` skill could own that.
- _Mintlify the product_ (mint.json, components, hosting) — this skill takes
  their writing guidance, not their tooling.
- _Specific Vale rule catalogs beyond the examples_ — mechanics.md shows the
  patterns; a project's actual rule set lives with the project.

## Design choices

- **Name is unprefixed** (`docs-writing`, not `skmtc-docs-writing`) because the
  content is project-agnostic. The SKMTC-specific touches — the tree mapping and
  the `verify-docs.ts` / friction-log pointers — are kept minimal so the skill
  stays portable.
- **House style preserved**: numbered sections, "principles that override
  default intuitions" opener, decision tables, task cards, and a verification
  checklist, matching `skmtc-generator` / `skmtc-cli` so the skill family reads
  uniformly.
- **"Seven principles" framing** mirrors the "N facts" opener convention of the
  sibling skills. Verify-first was added as principle #1 in v0.2.0 because the
  skill's writer is usually an LLM, and LLM-written docs fail differently from
  human-written docs (hallucinated flags, documented intent vs. behavior) — the
  highest-leverage correction goes first.
- **AI-agent readership is folded into every structural section** rather than
  ghettoized in one — AEO and human skimmability are the same optimization. The
  agent-as-_writer_ stance (verify-first) is separate and lives in §1.1.
- **Companions over one mega-file**: templates and mechanics are needed at
  different moments than the craft rules; splitting keeps the loaded artifact
  dense (positional attention, context budget) while the companions stay a Read
  away.

## Changelog

- **0.2.0 (July 2026)** — diversified sources beyond Mintlify (Diátaxis in
  depth, Google/Microsoft style guides, EPPO, Write the Docs, Docs for
  Developers, NN/g, Good Docs Project, Keep a Changelog, llms.txt, Vale). Added:
  verify-first principle (§1.1), the compass, type≠difficulty, per-type voice,
  recipes ruling, incremental application, word-level bad→good rules, global-
  audience rules, procedures section, EPPO structure rules (context / one level
  / link richly / conform to type), information scent, editing passes, ARID,
  deprecate-before-delete, llms.txt. Resolved the contested seams (decision log
  above). Split templates.md and mechanics.md out as companions. Compressed
  media/SEO/metrics. Added Bash to allowed-tools (running examples is part of
  the craft).
- **0.1.0 (July 2026)** — initial distillation from Mintlify guides plus the
  Diátaxis four-type model.

## Verification loop (wired 2026-07-06)

- **CI counterpart** — `deno/docs/verify-docs.ts` checks 4 and 5: the §3
  Diátaxis tree mapping stays in sync with the real directory layout (both
  directions, incl. the extending-mirrors-using claim), and a zero-tolerance
  filler-word guard (`simply`/`easily`/`obviously`/`as of this writing`) across
  the reader-facing tree. "just" and "currently" are deliberately not checked —
  too many legitimate uses (version-scoped capability statements); those stay a
  review concern. The seven pre-existing filler hits were fixed when the guard
  landed.
- **Eval coverage** — removed 2026-07-12 along with the `docs/evals/` harness
  (LLM-judge evals retired as unconvincing; the mechanical CI counterpart above
  remains the verification loop).

## Open questions

- Does this skill need trigger wiring into the user-level skill list
  (`~/.claude/skills/`) like the `skmtc-*` skills, or is repo-local loading
  sufficient? (Currently symlinked at user level.)
- Whether §10–§11 (media, discoverability) should also move to a companion if
  SKILL.md grows further.
  • mechanics.md 6.3 KB 
    # Mechanical enforcement and the machine surface

Companion to `SKILL.md` — the automatable subset of the craft rules, and the
llms.txt format. Read when wiring docs checks into CI or standing up the
machine-readable surface, not at the moment of writing a page.

Distilled July 2026 from https://vale.sh, https://llmstxt.org,
https://github.com/DavidAnson/markdownlint,
https://github.com/lycheeverse/lychee, and GitLab's docs-testing pipeline
(https://docs.gitlab.com/development/documentation/testing/).

## What's automatable vs. not

Automatable (put in CI, stop relitigating in review): filler words,
banned/time-bound terms, terminology consistency, heading hierarchy, code-fence
language tags, missing alt text, broken links, sentence-case headings, example
execution.

Not automatable (the review's actual job): type purity, verified behavior claims
(SKILL.md §1.1), information scent of headings, persona fit, whether the opening
establishes context, alt-text _quality_.

## Vale — prose linting

Vale (https://vale.sh) is a single-binary CLI that lints prose against YAML
rules; it's markdown-aware (skips code blocks by default) and ships ready-made
packages for the major style guides: `Google`, `Microsoft`, `write-good` (weasel
words, passive voice), `proselint`, `alex` (insensitive language).

Minimal realistic `.vale.ini` for a markdown docs tree:

```ini
StylesPath = .vale/styles
MinAlertLevel = warning
Packages = Google

# Project-accepted/rejected terms:
# .vale/styles/config/vocabularies/Docs/{accept.txt,reject.txt}
Vocab = Docs

[*.md]
BasedOnStyles = Vale, Google, Docs
# Tone down an inherited rule without forking the package:
Google.Passive = suggestion
```

Custom house rules go in `.vale/styles/Docs/*.yml`. The rule types that map
directly onto SKILL.md's style rules:

**`existence` — ban filler words** (§4):

```yaml
# .vale/styles/Docs/Filler.yml
extends: existence
message: "Remove filler: '%s' adds no information."
level: error
ignorecase: true
tokens:
  - simply
  - easily
  - just
  - obviously
  - clearly
  - of course
```

A second `existence` rule with `currently|new|soon|as of this
writing|latest`
enforces timeless docs (§4) — scope it to exclude changelog paths via a per-glob
section in `.vale.ini`.

**`consistency` — one term per concept** (§4). `either` lists variant pairs of
which only one may appear per document:

```yaml
# .vale/styles/Docs/TermConsistency.yml
extends: consistency
message: "Inconsistent term: pick one of '%s' per document."
level: error
ignorecase: true
either:
  API key: API token
  sign in: log in
  config file: configuration file
```

**`substitution` — enforce the canonical term**, with editor auto-fix:

```yaml
# .vale/styles/Docs/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: warning
ignorecase: true
action:
  name: replace
swap:
  "e-mail": email
  "repo": repository
  "whitelist": allowlist
  "blacklist": blocklist
```

Other rule types available: `occurrence` (e.g. max sentence length),
`repetition`, `conditional`, `capitalization` (e.g. sentence-case headings),
`metric` (readability thresholds), `spelling`, `sequence`, `script`.

## Structural checks — markdownlint + lychee

**markdownlint** (`markdownlint-cli2` in CI) — the rules that carry docs
quality, mapping to SKILL.md §6:

- `MD001` — heading levels increment by one (no H2 → H4)
- `MD040` — fenced code blocks declare a language
- `MD045` — images have alt text
- `MD042` — no empty links

**lychee** — async link checker for markdown. Run internal-link checks on every
PR (`--offline`, or an include/exclude split) and external-link checks on a
weekly schedule — external checks on every PR are flaky (rate limits, transient
5xx). Supports `.lycheeignore` and `--accept 200,429`.

GitLab's docs pipeline pairs exactly these: Vale + markdownlint (+ link
checking) as the standard stack.

## Testing code examples

A fenced code block is a claim; untested claims rot (SKILL.md §1.7, §7).
Patterns by ecosystem:

- **Rust**: doctests built in; `mdbook test` executes blocks in a markdown book.
- **Python**: `pytest --doctest-glob='*.md'`; or **pytest-examples** (Pydantic
  team) — finds Python blocks in markdown, lints, executes, checks printed
  output, and can rewrite blocks in place.
- **OCaml**: MDX, integrated into dune.
- **Generic / this repo**: extract fenced blocks by info-string tag with a small
  script and execute them in CI; at minimum, type-check snippets by
  concatenating them into a scratch module. Mark deliberately non-runnable
  fragments with a distinct tag so the untagged default stays "this must run".

In this tree, `deno/docs/verify-docs.ts` hosts docs-writing's mechanical checks:
the Diátaxis tree-mapping sync and the filler-word guard (checks 4 and 5). A
fenced-block extractor running under `deno check` would cover the TypeScript
examples next.

## llms.txt — the machine-readable docs index

Spec: https://llmstxt.org. A markdown file at the site root giving LLMs a
curated map of the docs — context windows can't hold a whole site, so hand
agents a short index of clean markdown instead of letting them scrape HTML.

Format (order fixed; only the H1 is required):

```markdown
# Project name

> One-paragraph summary: the key facts an agent needs first.

Optional freeform background paragraphs (no headings).

## Section name

- [Page title](https://url): one-line description — what it covers and when to
  read it

## Optional

- [Secondary link](https://url): links here may be skipped when context is short
```

- `llms.txt` is the index; `llms-full.txt` concatenates the entire corpus into
  one file so a single URL loads full context. Ship both if the corpus fits a
  context window; the index alone otherwise.
- Entry descriptions: one line, concrete, front-loaded — "Reference for the runs
  API: endpoints, auth, pagination", not "Learn more about runs".
- Test it: expand the file into an LLM context and ask real product questions
  against it.
- Honest caveat: no major crawler is confirmed to request llms.txt unprompted.
  Its proven value is deliberate use — humans and agents fetching it as context
  — not passive SEO. Adoption is near-standard among dev-tool docs (Anthropic,
  Stripe, Cloudflare, Vercel; Mintlify auto-generates it), so its absence now
  reads as a gap.
- The companion convention: serve a clean `.md` variant of every page (append
  `.md` to the page URL).
  • SKILL.md 37.5 KB 
    ---
name: docs-writing
version: 0.2.0
description: |
  Write, restructure, or review documentation — tutorials, how-to
  guides, reference pages, concept/explanation docs, API references,
  READMEs, changelogs, release notes, and troubleshooting guides.
  Distills documentation craft from Mintlify's guides (compiled from
  technical writers at Stripe, GitHub, Amplitude, and Anaconda), the
  Diátaxis framework (including the compass and per-type voice), the
  Google and Microsoft style guides, Every Page Is Page One, Write
  the Docs, and Docs for Developers: audience analysis, content-type
  selection, style and word-level rules, procedure writing, structure
  for humans and AI agents, code-example standards, page templates
  (templates.md), mechanical enforcement and llms.txt (mechanics.md),
  maintenance, and success metrics.

  Use this skill when the user asks to "write docs", "document this
  feature", "improve this page", "review these docs", "write a
  tutorial / how-to / reference page", "structure the docs",
  "write API documentation", "write a README / changelog", or when
  authoring any file under a `docs/` tree. For SKMTC docs
  specifically, this skill governs the *craft* (what makes the page
  good); the content split between skills, `llms.md`, and the docs
  tree is governed by `docs/skills/README.md`.

  Distinct from `skmtc-retro` (captures observations about work) and
  the `skmtc-*` operational skills (guide doing the work) — this
  skill guides writing *about* the work for readers.
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
metadata:
  internal: true
---

# Writing documentation

Documentation craft distilled for the moment of writing. The core stance:
**people don't read docs for fun; they arrive with a goal — and they read at
most ~20–28% of the words on a page** (NN/g). Every rule below serves getting
the reader from arrival to accomplished goal with minimum friction — and the
same properties that serve a skimming human serve an AI agent reading the page.

Companion files, read on demand:

- `templates.md` — page skeletons + quality bars for how-to, tutorial,
  reference, concept, README, changelog, release notes, and troubleshooting
  pages.
- `mechanics.md` — mechanical enforcement (Vale, markdownlint, link checking,
  testing code examples) and the llms.txt format.

## 1. The seven principles that override default writing intuitions

Writing docs is not writing prose. These override what generic "good writing"
instincts would suggest:

1. **Verify before you document.** Never document behavior you haven't executed,
   observed, or read in the source. LLM-written docs fail here in characteristic
   ways: plausible flags that don't exist, documented _intent_ instead of actual
   behavior, invented defaults, hedged claims papering over unchecked ones. If
   you can't run it, read the code that implements it; if you can do neither,
   mark the claim unverified rather than asserting it. This is the docs analogue
   of `skmtc-debug`'s verify-first stance.

2. **One page, one content type, one persona.** Decide _before_ drafting whether
   the page is a tutorial, how-to, reference, or explanation (§3), and who it's
   for (§2). "Writing for multiple audiences leads to compromises that satisfy
   no one." A page that teaches AND exhaustively catalogs AND justifies design
   does none of them well.

3. **Lead with the answer, not the context.** Readers scan in an F-pattern and
   abandon pages whose opening doesn't confirm what the title promised. Put the
   outcome or instruction in the first paragraph; front-load the
   information-carrying words in headings. A reader should be able to leave
   after the first paragraph having gotten what they came for.

4. **The curse of knowledge is the default failure mode.** You know how
   everything works; the reader doesn't. State prerequisites explicitly, define
   acronyms on first use, never assume internal conventions (naming schemes,
   auth flows, team shorthand) are known. Validate against real evidence —
   support tickets, friction logs, user questions — not assumptions. Test: could
   someone who joined yesterday follow this?

5. **Every page is page one.** Readers arrive from search engines, deep links,
   and AI retrieval — never at your table of contents. Each page must establish
   its own context (what it covers, who it's for, what it assumes) in its
   opening. Reading-order dependencies ("as mentioned above", "in the previous
   section") are forbidden; link to supporting material instead.

6. **Code examples are load-bearing, not decorative.** Many readers only read
   the code blocks. Every example must be complete and runnable as-copied —
   imports, setup, the call, response handling. "A code example is worth a
   thousand words."

7. **Wrong docs are worse than no docs.** "Consider incorrect documentation to
   be worse than missing documentation" (Write the Docs). Outdated or misleading
   content wastes users' time and erodes trust in the whole product. When you
   can't maintain a page, delete it — removal often serves users better than
   retention.

## 2. Know your audience

Center the reader's goal, not the product's feature list.

### The four personas

| Persona                  | Needs                              | Serve with                                                                          |
| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------- |
| Technical decision maker | Evaluate fit and architecture      | Overviews, concept docs, comparison-friendly framing                                |
| New end user             | Get to first success fast          | Getting-started tutorial, quickstart                                                |
| Integrating developer    | Implement correctly                | How-tos, reference, complete examples                                               |
| AI agent / LLM           | Retrieve and act without inference | Structure, explicit prerequisites, self-contained sections, unambiguous terminology |

Pick **one** primary persona per page. The AI-agent persona is served by the
same properties that serve skimming humans — clear headings, semantic markup,
defined terms, runnable examples — so it rarely needs separate pages, but it
does raise the bar on explicitness (§6).

### Defeating the curse of knowledge

- Talk to users (or their proxies: support, UX research, product). Harvest the
  _terminology they actually use_ — it often differs from internal naming, and
  it's what they'll search for.
- **Keep a friction log**: use the product as a new user would and record every
  step — expected vs. actual, every confusion, workaround, and surprise. Each
  entry is either a docs fix or a product bug; file it as one or the other.
  (This ecosystem already runs one at `docs/friction-log/`.)
- Use the five W's to define a page's scope before writing: who is this for,
  what will they accomplish, why would they need it, where/when does it apply —
  then how.
- Embed with support: recurring tickets are a ranked list of doc gaps.
- Test docs by asking an AI assistant product questions and seeing whether the
  docs let it answer correctly — a cheap proxy for "does the page carry its own
  context".
- **Assume the reader is qualified** for the page's task; don't explain basics
  inline. Give unqualified readers enough context to _recognize_ they're on the
  wrong page, plus a link to where they can qualify themselves — a page "can't
  bring every possible reader up to speed without becoming a textbook."
- Don't over-document niche edge cases in guides; route those to community
  channels and keep guides focused on majority paths. (Reference is different —
  see §3: exhaustive within its scope.)

## 3. Content types (Diátaxis)

Four types, distinguished by what the reader is trying to do. Assign each page
exactly one type before drafting.

| Type             | Reader's goal               | Reader's mode | Structure                            | Voice                              |
| ---------------- | --------------------------- | ------------- | ------------------------------------ | ---------------------------------- |
| **Tutorial**     | "Teach me by doing"         | Study         | Linear steps, guaranteed outcome     | Guiding: "we", first person plural |
| **How-to guide** | "Solve my specific problem" | Work          | Problem → solution steps, may branch | Direct, conditional imperatives    |
| **Reference**    | "Give me the precise fact"  | Work          | Scannable catalog, consistent format | Neutral, terse, austere            |
| **Explanation**  | "Help me understand why"    | Study         | Discursive, conceptual               | Reflective, comparative            |

### The compass — when the type is unclear

Ask two questions about the content (works at page, section, or sentence level):

1. Does it inform **action** (doing) or **cognition** (thinking)?
2. Does it serve **acquisition** of skill (study) or **application** of skill
   (work)?

action + acquisition → tutorial · action + application → how-to · cognition +
application → reference · cognition + acquisition → explanation.

**Type is function, not difficulty.** An advanced course is still a tutorial (a
lesson, safely in the instructor's hands); a trivial one-step procedure is still
a how-to (a worker's task). "Beginner content = tutorial, advanced content =
how-to" is Diátaxis's most common and most harmful misreading — classify by
study-vs-work, never by difficulty.

Navigation should mirror the split: Getting Started → Guides → Reference →
Concepts. The SKMTC docs tree instantiates this as `using/tutorials/` +
`using/how-to/` + `using/recipes/`, `authoring/` (same trio), `reference/`, and
`concepts/` + `explanation/`. **Recipes are how-to guides in recipe form** — the
recipe is Diátaxis's own model for the type (assumes competence, answers one
specific question, no teaching). The four types classify _needs_, not directory
names; a section may be named anything so long as each page serves one need
well.

### Writing rules per type

**Tutorials** — learning-oriented:

- Open by stating exactly what the reader will have built/achieved at the end.
- First person plural, teacher's voice: "In this tutorial, we will…";
  unambiguous imperatives: "First, do x. Now, do y."
- Every step delivers a **visible result**, and the text names it: "The output
  should look something like…" — checkpoints let readers self-verify they're on
  track.
- Small incremental steps; a tutorial "doesn't offer choices or alternatives" —
  one carefully-managed path.
- Teach through experience, not explanation — link to explanation docs rather
  than digressing: "We must do x before y because… (see [explanation] for
  details)."
- Must work every time: "so well constructed that things can't go wrong" — a
  tutorial that fails at step 4 loses the user, possibly permanently. Expect
  high maintenance cost as the product evolves.

**How-to guides** — task-oriented:

- Title is the task in the user's words ("Skip operations for one generator"),
  not the feature's name.
- **Conditional imperatives** carry the branching: "If you want x, do y. To
  achieve w, do z." (Tutorials never branch; how-tos usually do.)
- About goals, not machinery: address the real-world task, not a walkthrough of
  the tool's controls.
- Assume foundational knowledge; state the specific prerequisites, then skip the
  obvious steps.
- "Practical usability is more helpful than completeness" — only the context
  necessary for _this_ task; offload option inventories to reference: "Refer to
  the x reference for a full list."

**Reference** — information-oriented:

- "Austere and uncompromising": describe, and _only_ describe. Neutral statement
  of fact; no instruction, no rationale.
- Structure mirrors the product's structure, and entry order mirrors the source
  of truth, so drift is visible.
- Maximize scannability: tables, identical per-entry format, parallel phrasing,
  one naming convention across every entry.
- Copy-paste-ready examples per entry (examples illustrate without explaining —
  they're welcome); required vs. optional marked explicitly; constraints and
  defaults stated, not just the name restated.
- Exhaustive within its declared scope — a reference that omits entries is
  broken in a way a how-to never is.

**Explanations** — understanding-oriented:

- The "About" test: an explanation title should tolerate an implicit "About …"
  prefix ("About user authentication"). If it can't, the page probably isn't
  explanation.
- Cover design decisions, constraints, and the alternatives that were rejected
  (and why).
- Opinion is allowed and required here: explanation "can and must consider
  alternatives, counter-examples or multiple different approaches."
- Explanation "tends to absorb other things" — expel instruction and technical
  description to their proper homes.

### Type-mixing smells

- A tutorial that pauses for three paragraphs of rationale → move the rationale
  to an explanation doc, link it.
- A tutorial offering choices ("you could also use…") → cut; one path.
- A reference entry with step-by-step setup → extract a how-to.
- A how-to that exhaustively lists every option → extract reference material,
  keep only the options the task needs.
- A how-to that keeps stopping to teach → trust the reader's competence; link
  the tutorial instead.
- Time-sensitive content (release notes, announcements) in evergreen docs →
  belongs in a changelog or blog (see `templates.md`).

**Scoped exception — API reference surfaces.** Reference pages for an HTTP API
may deliberately blend the catalog with per-language samples, request/response
pairs, and short usage notes (the Stripe pattern, §8). That blend is confined to
the API reference surface; docs-tree pages keep one type each.

### Applying Diátaxis incrementally

Don't restructure top-down into four empty boxes and shovel content in —
"Diátaxis changes the structure of your documentation from the inside." The
loop: choose something small; assess what user need it serves and how well;
decide on a single next action; do it and publish immediately. Documentation is
_never finished_ — but at every moment it can be _complete_: useful, correct,
and coherent at its current scope. Never hold back an improvement waiting for
"done".

## 4. Style and tone

- **Cut ruthlessly — within a section.** Every unnecessary word taxes a reader
  who is there to get something done. But brevity governs sentences and
  paragraphs; **explicitness governs boundaries**: restating context at a page
  or section opening is not filler — it's the entry point for a reader (or
  retrieval chunk) landing there (§1.5). Cut words, not context.
- **Active voice, imperative mood.** "Create a file", not "a file should be
  created".
- **Second person.** "You" — the doc serves the reader's task. (Exception:
  tutorials use "we" — §3.)
- **Short paragraphs** (2–4 sentences), meaningful headings, lists for
  enumerable things, tables for structured facts.
- **One term per concept, everywhere.** "API key" and "API token" used
  interchangeably reads as two different things. Pick one; grep for the other
  (enforceable with a Vale `consistency` rule — `mechanics.md`).
- **Don't narrate the obvious.** "Click Save to save" is negative value.
  Document what isn't intuitive.
- **Spelling and grammar are trust signals.** Errors in the docs read as errors
  in the product.

### Word-level rules (bad → good)

The high-leverage subset of the Google and Microsoft style guides — rules a
fluent writer (or LLM) gets wrong by default:

- **Delete "simply", "easily", "just", "obviously", "of course".** What's easy
  for the writer isn't for the reader; the sentence survives without them.
  "Simply run the installer" → "Run the installer."
- **No "please" in instructions.** "Please click Save" → "Click Save."
- **Present tense for product behavior; never "will" or "would".** "The server
  will send an acknowledgment" → "The server sends an acknowledgment."
- **Timeless docs: ban "currently", "new", "now", "soon", "as of this writing",
  "latest", "old", "eventually".** "The emulator now supports filters" → "The
  emulator supports filters." If "new" is unavoidable, anchor it to a date.
  Exception: changelogs and release notes.
- **No anthropomorphism.** Software doesn't want, think, see, know, or care.
  "The PC sees a new device" → "The PC detects a new device."
- **"may" = permission only; "might" = possibility; "can" = ability.** "The call
  may fail" → "The call might fail."
- **"should" is ambiguous** — use "must" for requirements; rewrite
  recommendations as "we recommend" or a direct imperative.
- **Spell out Latin abbreviations**: "e.g." → "for example", "i.e." → "that is";
  avoid "etc." (finish the list or use "such as").
- **"allows you to" / "enables you to" → "lets you"** — or make the reader the
  subject: "The API allows you to filter results" → "Filter results with…".
- **"in order to" → "to"; "utilize"/"leverage" → "use".**
- **Start instructions with the verb** — kill "You can…" and "There is/are…"
  openers. "You can access the settings from…" → "Open the settings from…".
- **Sentence-style capitalization for all headings.** Never Title Case. Oxford
  comma always. Contractions are fine.
- **"select"** for UI interaction (not "click"/"tap" — accurate for keyboard,
  touch, and assistive tech); **select/clear** checkboxes (never
  "check"/"uncheck").
- **Never inflect code identifiers** — attach a noun and inflect that: "`Node`s"
  → "`Node` objects"; "`ADDRESS`'s value" → "the `ADDRESS` constant's value".
- **Inclusive defaults**: allowlist/blocklist, primary/replica, placeholder (not
  dummy), "stops responding" (not hangs), singular "they" (never "he/she").

### Writing for a global audience

Docs are read by non-native speakers and machine translation:

- Short sentences, one idea each; no more than two clauses chained with
  and/or/but.
- Keep optional function words — "Verify all tables migrated" → "Verify **that**
  all tables **were** migrated."
- Avoid ambiguous connectives: "once" → "after"/"when"; "while" →
  "although"/"during"; "since"/"as" → "because" (unless temporal).
- Place "only" immediately before the word it modifies: "Only request one token"
  → "Request only one token."
- No noun stacks (max two nouns as modifiers), no phrasal verbs where a single
  verb exists, no idioms, colloquialisms, humor, or culture-bound references.
- Dates: spell out the month ("January 19, 2026") or ISO 8601 (2026-01-19);
  never 04/15/17; never seasons.

Lean on the Google or Microsoft style guide for the long tail; automate
enforcement with Vale in CI (`mechanics.md`) rather than relitigating style in
review.

## 5. Writing procedures

Step sequences have their own mechanics (Google/Microsoft procedure rules):

- **Numbered list; one action per step.** Combine actions only when they're
  trivial and happen in the same place.
- **Location and purpose before action**: "In Google Docs, select **File >
  New**" — not "Select **File > New** in Google Docs". "To start a new run,
  click…" — the goal first, so the reader can skip steps they don't need.
- **State a step's result in the same paragraph as the action**, after it — not
  as its own numbered step: "Drag the tiles to an open space. When a gray bar
  appears, release them."
- **A single-step procedure is one bullet**, not "1.".
- **Optional steps start with "Optional:"**.
- **End with the completing action** — the **Save**/**Apply** step; don't leave
  the procedure hanging. If the end state isn't obvious, say what success looks
  like.
- **Menu paths**: bold items separated by ">" (**File > New > Document**); use
  one convention throughout, and only when every hop uses the same interaction.
- **One method per procedure.** Alternatives and keyboard shortcuts belong in a
  reference table, not woven into the steps.
- **Task-phrased, parallel headings** ("Create a profile", "Add an account");
  don't follow the heading with a sentence that repeats it.

## 6. Structure for humans AND AI agents

The same page properties serve skimming humans, search engines, and LLM
retrieval. Optimize once:

- **Establish context in the opening**: what the page is about, who it's for,
  where it fits — position in the nav tree doesn't travel with the page into a
  search result or a retrieval chunk.
- **Descriptive headings with honest information scent.** Readers choose links
  and sections by an estimate of what's behind them — from the label alone.
  "Rate limiting" beats "Keeping things under control"; phrase task headings the
  way a user would ask ("Rotate an API key"). A heading should answer "is my
  answer in this section?" without reading the section. Over-promising titles
  get the page abandoned and burn trust.
- **Semantic markup**: proper heading hierarchy (H2 → H3 → H4, no skipped
  levels), lists for enumerations, tables for structured data (headers in the
  first row only, no merged cells), fenced code blocks with language tags.
- **Explicit prerequisites** at the top of task pages — humans skip them at
  their own risk; AI agents cannot infer unstated context.
- **Definitions before edge cases; common cases before advanced.**
- **Stay on one level.** Don't oscillate between high-level principle and
  low-level detail on one page; link _up_ to concepts and _down_ to reference
  and let the reader change levels when they choose.
- **Link richly, along subject affinity** — every page is a hub. Descriptive
  anchors ("see the enrichments reference"), never "click here"; no positional
  language ("above"/"below" → name the section or link it).
- **Self-contained sections**: a section pulled out of the page by a retrieval
  system should still make sense. Restate the subject noun (not "it"); restate
  (briefly) rather than relying on "as mentioned above".
- **Conform to type**: pages with the same purpose share the same sections in
  the same order (`templates.md`) — predictability serves scanners, and a
  defined shape makes gaps visible.
- **Document error scenarios and deprecations explicitly** — error strings are
  among the highest-value search and retrieval targets, and the least often
  documented.
- Delete or clearly mark outdated content: AI retrieval surfaces deprecated
  pages with no sense of staleness.
- **Ship the machine surface**: an `/llms.txt` index (and `llms-full.txt` if the
  corpus fits a context window) — format and rules in `mechanics.md`.

### Validating the structure

- Analytics: where do readers enter, what do they search for ( especially
  searches with zero results), where do they exit.
- Session paths: do readers follow the navigation you designed, or fight it?
- Direct tests: watch a user (or a new hire — an excellent proxy) try to answer
  a specific question using only the docs.
- Common pitfalls: overloaded top-level categories (seven items is a comfortable
  limit for an unordered list), essential pages buried three levels deep,
  section labels only insiders understand.

## 7. Code examples

The most-read part of any developer doc. Standards:

- **Runnable as-copied.** Full workflow: imports, setup, authentication
  placeholder, the call, response handling. A fragment that needs unstated
  scaffolding is a support ticket.
- **Realistic data** — not `foo`/`bar`; use values shaped like real usage so
  readers can map the example onto their case.
- **Placeholders in `UPPER_SNAKE_CASE`**, followed by "Replace the following:"
  with one line per placeholder in order of appearance.
- **Show the expected output/response** alongside the request, so readers can
  verify success without guessing.
- **Include error handling** in longer examples — it's where real integrations
  spend their time.
- **Multiple languages via tabs** where the audience spans ecosystems; every
  tab's example kept equivalent.
- **Test examples in CI.** A fenced code block is a claim; untested claims rot,
  and an example that rots is worse than none (§1.7). Extraction and doc-testing
  patterns per ecosystem are in `mechanics.md`; mark deliberately non-runnable
  fragments so the untagged default stays "this must run".

## 8. API documentation

The specialized high-stakes case. Structure around the developer's journey, and
measure it by **time-to-first-successful-call**.

### Required components

| Component       | Bar to clear                                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Getting started | Working integration inside ~15 minutes; never buried                                                            |
| Authentication  | Step-by-step credential setup, token placement, expiry and rate limits, per-method examples (curl + SDKs)       |
| API reference   | Complete request/response cycles — paths, methods, parameters, schemas, status codes — not a bare endpoint list |
| Guides          | Organized by real tasks ("Send a message", "Accept a payment"), not by endpoint inventory                       |
| Error catalog   | Every error code with context and the _remediation_, including near-miss distinctions (400 vs 422)              |
| Changelog       | Timestamped, discoverable, flags breaking changes and deprecations loudly (`templates.md` for the format)       |

### Practices that separate the best API docs

- **Pair generated reference with authored guides.** Auto-generation from an
  OpenAPI spec is a starting point only — it has no editorial judgment, no
  use-case coverage, no workflow ordering. Layer opinionated guides on top;
  never ship the generated reference alone.
- **Workflow-first organization** (the Stripe pattern): each reference page
  carries descriptive titles, per-language samples, realistic request/response
  pairs, and usage notes. This is the sanctioned type-blend — scoped to the API
  reference surface (§3).
- **Copy-paste-ready everywhere**, ideally with the reader's own test
  credentials injected when docs are behind a logged-in state — but never
  _require_ login to read the docs; gated docs kill self-service evaluation.
- **Skimmable and searchable**: developers arrive with a task, not to read
  linearly.
- **Interactive playgrounds** on reference pages turn specs into executable
  experiences.
- **Design for LLM consumption**: consistent formatting and rich examples let AI
  assistants generate correct integration code from your docs — an adoption
  channel in its own right.

## 9. Page templates

`templates.md` holds compressed skeletons — ordered sections, a one-line note
per section, and the 2–3 quality criteria separating a good instance from a
mediocre one — for:

how-to guide · tutorial · reference entry · concept/explanation · README ·
changelog (Keep a Changelog format) · release notes · troubleshooting guide

Use them as the "conform to type" baseline (§6): start from the skeleton, delete
sections that genuinely don't apply, and keep the order. Two worth
internalizing:

- **README = cognitive funnel, not manual.** Broadest first — what it is (< 120
  chars), who it's for, a runnable usage example — so the reader can bail out at
  any depth having lost minimal time. Depth belongs in the docs tree; the README
  links there. License last.
- **Changelogs are for humans, not machines.** Never paste `git
  log`. Group by
  Added/Changed/Deprecated/Removed/Fixed/Security, newest first, ISO dates, an
  `[Unreleased]` section at the top, and _always_ announce deprecations one
  version before removal — selective entries "can be as dangerous as not having
  a changelog".

## 10. Media

Media is supplementary. **If the workflow is clear in text alone, don't add
visuals** — every asset is a maintenance liability that silently rots when the
UI changes. Screenshots for UI elements that are hard to describe; diagrams as
code (Mermaid — text-diffable) over image exports; video only for long
procedures, and only with captions. Non-negotiable: alt text on images
(descriptive and specific — "OAuth 2.0 flow", not "diagram"), and never present
information _only_ in an image — it's invisible to screen readers, search, and
AI retrieval alike.

## 11. Discoverability (SEO and AEO)

Most readers arrive from a search engine or an AI assistant, not your nav.
**Answer Engine Optimization is §6 done well** — there is no separate trick:
literal headings, self-contained sections, defined terms, stated prerequisites,
complete examples, documented errors and deprecations, loud deprecation markers.
The classic mechanical layer still applies: titles ~50–60 characters and meta
descriptions ~150–160 frontloading the terms users actually search (harvested
from user language, §2); descriptive link anchors; compressed images; a current
sitemap. Skip structured-data gymnastics unless you have evidence your audience
arrives through them.

## 12. Maintenance

Docs rot by default; only a system prevents it.

- **Docs-as-code**: docs live in git, change via PRs, deploy automatically,
  version alongside the code they describe. Review catches errors before
  publication and lets engineers contribute through tools they already use.
- **ARID, not DRY** — "Accept (some) Repetition In Documentation." Docs are read
  in fragments, so they can't be as DRY as code: single-source what you can,
  duplicate deliberately where the reader needs it in place — and give every
  duplicated fact one designated canonical home so drift is detectable (this
  ecosystem's selective-duplication policy in `docs/skills/README.md` is this
  principle applied).
- **Couple docs to shipping**: a user-facing change isn't done until its docs
  are updated — enforce in the definition of done or PR template, and automate
  detection of drift (e.g. flag when the OpenAPI spec changes but the guide
  didn't).
- **Automate the boring checks**: broken links, heading hierarchy, missing alt
  text, filler words, terminology consistency, example compilation — the full
  toolbox with configs is in `mechanics.md`.
- **Edit in sequenced passes, one concern each** — drafting and editing are
  different acts; never do both at once. The order: (1) technical accuracy — do
  the instructions produce the promised result; (2) completeness — can the
  reader succeed with what's here; (3) structure — do headings and prerequisites
  guide the reader; (4) clarity and brevity — cut. Self-review with the §13
  checklist first, then peer review with a _specific ask_, then expert technical
  review for complex topics.
- **Prioritize by impact, not schedule**: the 10 most-viewed pages get
  disproportionate attention. Use the traffic × rating grid:
  high-traffic/low-rating pages are the urgent queue; low-traffic/ high-rating
  pages hold patterns worth replicating.
- **Assign ownership.** Documentation without a named owner diffuses into no
  one's job and quietly dies.
- **Deprecate before deleting**: mark the content deprecated in place, point to
  the replacement, give notice — then delete what no longer serves users (§1.7).

## 13. Measuring success

Numbers require interpretation — "don't fall into the trap that a bigger number
means better performance."

| Signal                                     | Reading it honestly                                             |
| ------------------------------------------ | --------------------------------------------------------------- |
| Page views                                 | Interest — or bots, or a product bug driving people to the docs |
| Time on page                               | Engagement — or frustration hunting for an answer               |
| Zero-result searches                       | Direct gap list; the highest-signal analytic                    |
| Thumbs-up ratio                            | Target ~75%+; below that, the page misleads or misses           |
| Support ticket volume on documented topics | The docs' business case: each deflected ticket is the win       |
| AI-assistant query logs                    | What users actually ask, in their words — feeds §2              |

Compare against your own baseline over time, not absolute thresholds. Tie the
program to business outcomes: onboarding speed, support deflection, retention.

## 14. Pre-publish checklist

Before a page ships:

- [ ] Every behavioral claim verified — executed, observed, or read in source;
      anything unverifiable is marked, not asserted (§1.1)
- [ ] One content type, chosen via the compass if unclear; no type-mixing smells
      (§3)
- [ ] One primary persona; prerequisites stated at the top
- [ ] The answer/outcome appears in the first paragraph; the opening establishes
      context for a reader arriving from search
- [ ] Headings are descriptive, front-load key terms, and don't skip levels
- [ ] Every code example runs as-copied and shows expected output; non-runnable
      fragments are marked
- [ ] Terminology consistent — grep for known synonyms of key terms
- [ ] No filler (`simply|easily|just|obviously`), no time-bound words
      (`currently|new|soon`) outside release notes, present tense for product
      behavior (§4)
- [ ] Procedures follow §5: one action per step, location before action, results
      stated, completing action present
- [ ] Page conforms to its type's skeleton (`templates.md`)
- [ ] Errors and edge cases the reader will hit are documented
- [ ] Links have descriptive anchors and resolve; no positional language
- [ ] Images have alt text; media passes the "necessary?" test (§10)
- [ ] Title/description frontload searchable terms
- [ ] The page has an owner and a reason to exist that analytics could later
      confirm

## 15. Task cards

### Card: Documenting a new feature

1. Identify the persona and their goal (§2). Write the five W's.
2. **Verify the behavior first** (§1.1): run the feature, note the actual
   commands, flags, outputs, and failure modes — this raw material is the
   draft's skeleton and its fact-check.
3. Split the material by type (§3): quickstart steps → tutorial or how-to;
   option/flag inventory → reference; design rationale → explanation. Resist the
   single mega-page.
4. Outline first — every step the reader needs, then reorder to the reader's
   flow. Draft the how-to first (it forces the user-goal framing) from its
   `templates.md` skeleton, then extract reference entries, then backfill
   explanation.
5. Write and _run_ every code example.
6. Edit in passes — accuracy, completeness, structure, brevity (§12) — then run
   the §14 checklist; place pages in the tree by type.

### Card: Reviewing/auditing an existing page

1. Determine its intended type (use the compass, §3) and persona. If
   undeclarable, that's finding #1.
2. Check the opening: does it establish context and state what the page
   delivers?
3. Run examples. Diff terminology against the rest of the docs.
4. Check staleness against the product's current behavior — wrong content is the
   highest-severity finding (§1.7).
5. Grep for the mechanical smells: filler words, time-bound words, "click here",
   skipped heading levels (§14).
6. Verdict per finding: fix, split (type-mixing), or delete.

### Card: Standing up docs for a new project

1. Skeleton by type: Getting Started → How-to Guides → Reference → Concepts
   (§3), pages from `templates.md`.
2. Write the getting-started path first and make it bulletproof — working result
   in ≤15 minutes.
3. Reference next (breadth), explanations last (depth).
4. Wire the maintenance system before content grows: docs-as-code, link
   checking, prose lint, docs-updated-with-change policy, and the machine
   surface (llms.txt) — configs in `mechanics.md`.
5. Thereafter improve incrementally (§3): one small published step at a time;
   never a big-bang restructure.

## 16. Sources

Distilled July 2026 from:

- Mintlify Guides — https://mintlify.com/guides/introduction
  (`know-your-audience`, `content-types`, `writing-style-tips`, `navigation`,
  `media`, `seo`, `maintenance`, `success`), itself compiled from interviews
  with technical writers at Stripe, Amplitude, Anaconda, and GitHub; plus
  Mintlify's API-documentation recommendations and developer-docs blog posts
- Diátaxis framework — https://diataxis.fr (the four types, the compass,
  tutorials-vs-how-to, complex hierarchies, per-type language guidance, quality;
  Daniele Procida)
- Google developer documentation style guide —
  https://developers.google.com/style (word list, tense, anthropomorphism,
  timeless documentation, procedures, link text, accessibility, translation)
- Microsoft Writing Style Guide — https://learn.microsoft.com/en-us/style-guide/
  (top 10 tips, bias-free communication, global communications, step-by-step
  instructions)
- Every Page Is Page One — Mark Baker (the seven characteristics of EPPO topics;
  information foraging) — https://everypageispageone.com
- Write the Docs — https://www.writethedocs.org/guide/ (docs principles incl.
  ARID, docs-as-code, style guides)
- Docs for Developers (Bhatti, Corleissen, Lambourne, Nunez, Waterhouse) —
  https://docsfordevelopers.com (friction log, drafting process, editing passes,
  content taxonomy)
- Nielsen Norman Group — how little users read, the F-shaped pattern,
  information scent — https://www.nngroup.com/articles/
- The Good Docs Project templates — https://thegooddocsproject.dev (via
  `templates.md`)
- Keep a Changelog 1.1.0 — https://keepachangelog.com (via `templates.md`)
- Art of README + standard-readme (via `templates.md`)
- llms.txt spec — https://llmstxt.org; Vale — https://vale.sh; markdownlint;
  lychee (via `mechanics.md`)
  • templates.md 9.7 KB 
    # Page templates

Compressed skeletons per page type: ordered sections, a one-line note per
section, and the quality criteria that separate a good instance from a mediocre
one. Companion to `SKILL.md` §9 — start from the skeleton, delete sections that
genuinely don't apply, keep the order ("conform to type", SKILL.md §6).

Distilled July 2026 from The Good Docs Project templates
(https://thegooddocsproject.dev/template/, source repo
https://gitlab.com/tgdp/templates), Keep a Changelog 1.1.0
(https://keepachangelog.com/en/1.1.0/), Art of README
(https://github.com/hackergrrl/art-of-readme), and standard-readme
(https://github.com/RichardLitt/standard-readme).

## How-to guide

```
# {Verb} {object}                — bare-infinitive task title ("Connect to the VM
                                   instance"), not an "-ing" form or a feature noun
Overview                         — 1–2 sentences: "This guide shows you how to {task}."
                                   Optionally when/why you'd do it
Before you start (optional)      — bulleted prerequisites: access, tools, prior setup
## {Task name}                   — numbered steps, each starting with an action verb
   Step                          — instruction + optional context/code + expected result
   Substeps                      — only when a step genuinely decomposes
## {Sub-task} (optional)         — only for big tasks; same step structure
See also                         — related how-tos, concepts, troubleshooting
```

Quality bar:

- **One task per page**, documenting the single safest/most common method —
  never two ways to do the same thing. Max ~8–10 steps before splitting into
  sub-tasks.
- **No concept explanations in the body**; conditional imperatives ("If you want
  X, do Y") carry the branching; link out at the bottom, not inline everywhere.
- **Tested end-to-end** against the current release, in order.

## Tutorial

```
# {Tutorial title}
Overview                         — what you'll build, audience, and verb-led learning
                                   objectives: "By the end, you'll be able to {verb}…"
Background (optional)            — product context / why this matters
Before you start                 — ALL prerequisites: knowledge, software, environment
## {Stage} (repeat per stage)    — brief context, then numbered imperative steps
   Each step                     — instruction + code + expected result (checkpoint)
Summary                          — the skills actually gained
Next steps                       — follow-on tutorials, tasks, or docs
```

Quality bar:

- **Guaranteed success**: a managed start-to-end path that eliminates the
  unexpected; assume no practical knowledge; state every tool and config.
- **Checkpoints everywhere**: every step shows its expected result so the
  learner self-verifies.
- **Learning-oriented**: objectives written first and used to scope the content;
  the summary proves they were met.

## Reference entry

```
# {Reference title}
{Scope statement}                — 1–2 sentences: what this lists, how it relates to
                                   other docs
## {Entry group}                 — table or structured list; SAME format and order for
                                   every entry, mirroring the source of truth
   Field table                   — Field | Description | Example
   Command table                 — Command | Description | Argument(s) | Example
   Per parameter                 — required vs optional explicit; concrete example value;
                                   constraints and defaults stated
## Commands (optional)           — code blocks where a table is too cramped
```

Quality bar:

- **Ruthless consistency**: identical columns, phrasing pattern, and ordering —
  the reader predicts where information lives before looking.
- **Every entry has an example** and an explicit required/optional designation;
  descriptions state constraints and defaults, never just restate the name.
- **Entry order mirrors the code/API documented**, so drift is visible.

## Concept / explanation

```
# {Concept name}                 — tolerates an implicit "About …" prefix
Intro (no heading)               — the concept, why it matters, what this page covers
Definition                       — "{X} is …" / "{X} solves …"; diagram with caption
Background (optional)            — origin, design rationale, alternatives rejected
Use cases                        — what the reader can do once they understand this
Comparison (optional)            — table vs. alternatives/related options
Related resources (optional)     — links grouped by kind
```

Quality bar:

- **Zero procedural steps** — numbered instructions mean the content belongs in
  a how-to; link instead.
- **Anchored in the reader's problem**: use cases and comparisons say _when_ to
  reach for this, not just what it is.
- **One concept per page**, with a definition a newcomer could quote.

## README

```
# {Project name}                 — matches the repo/package name; badges few + meaningful
One-liner                        — <120 chars answering "what is this?"; screenshot/demo
                                   if visual
Who this is for                  — target user + objective; caveats/limitations UP FRONT
Table of contents                — only if the README exceeds ~100 lines
Install                          — copy-pasteable block; prerequisites first
Usage                            — the smallest real, runnable example in action
API (optional)                   — signatures, or a link to the full reference
Troubleshooting / FAQ (optional) — issue → solution for the top failure modes
Contributing                     — where to ask, PR expectations
Additional docs / help           — links to the docs tree and support channels
License                          — SPDX name + owner; ALWAYS the final section
```

Principles:

1. **Cognitive funnel**: broadest → most specific, so the reader can bail out at
   any depth having lost minimal time. The widest end answers "is this what I
   need?" before anything else.
2. **The README is a filter, not a manual**: say what it is, show it in action,
   show how to use it. Depth lives in the docs tree.
3. **Usage before API/installation detail** — a runnable example communicates
   fit faster than prose.
4. **As short as possible without being shorter**; never rely on images for
   critical information.
5. Docs are complete "when someone can use your module without ever having to
   look at its code" (standard-readme).

## Changelog (Keep a Changelog)

```
# Changelog
## [Unreleased]                  — accumulate upcoming changes; at release, retitle
## [X.Y.Z] - YYYY-MM-DD          — SemVer + ISO 8601; newest first; version links to diff
### Added                        — new features
### Changed                      — changes in existing functionality
### Deprecated                   — soon-to-be-removed (announce BEFORE removing)
### Removed                      — now-removed features
### Fixed                        — bug fixes
### Security                     — vulnerability fixes, called out explicitly
## [X.Y.W] - YYYY-MM-DD [YANKED] — pulled releases stay listed, tagged
```

Principles: changelogs are **for humans, not machines**; every version gets an
entry; group by change type; latest first; ISO dates; say whether you follow
SemVer. Entries start with a verb and describe the user-visible effect.

Anti-patterns:

- **Commit-log dumps** — commits document code evolution; a changelog
  communicates noteworthy differences to users.
- **Ignoring deprecations** — users must be able to upgrade to a version listing
  the deprecation, migrate, then upgrade past the removal.
- **Regional dates** — anything but YYYY-MM-DD is ambiguous.
- **Selective entries** — partial coverage "can be as dangerous as not having a
  changelog"; it destroys trust in all of it.

## Release notes (audience-facing, per release)

```
# Release notes — {Product} {version}
{Release date}                   — + optional 1–3 sentence summary
## New features                  — **Name** + what it enables + the user benefit
## Features requiring action     — anything needing config/migration to activate
## Improvements                  — quantified where possible
## API updates                   — endpoint and behavior changes for integrators
## Bug fixes                     — "Fixed issue where {problem}…"
### Known issues                 — acknowledged problems + fix status
## Deprecation notices           — feature + end-of-support date + migration path
```

Difference from a changelog: **benefit-first prose, not diffs** ("you can
now…"); action items separated so users can scan for "what do I have to do?";
deprecations always pair a sunset date with a named migration path.

## Troubleshooting guide

```
# Troubleshooting {product/feature}
Scope statement                  — what this guide covers
## {Symptom}                     — heading = what the user SEES: exact error text or
                                   the observable misbehavior (repeat per symptom)
### Cause                        — one cause at a time; multiple causes → multiple blocks
### Solution / workaround        — steps for THIS cause, ending with what success
                                   looks like
### For more information         — related articles, runbooks
```

Quality bar:

- **Symptom-first organization** — what the user experiences and would search
  for, never cause-first or architecture-first.
- **Strict symptom → cause → resolution triples**; every resolution states the
  expected post-fix behavior.
- **Error text quoted exactly** so Ctrl-F and search engines hit.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude