Documentation
Docs are part of the product. This skill governs their structure and quality; for the voice of the prose, REQUIRED SUB-SKILL: marketing-voice.
The backbone rule
Every page is exactly ONE Diátaxis type — tutorial, how-to, reference, or explanation. A page that serves four needs serves none.
This is the defect agents miss most, because a clean layout hides it. Both observed baselines failed here: an authoring agent fused explanation + a "quick-start arc" + four reference tables into one page and called it a "task-completion arc"; an audit agent praised the same fusion as "progressive disclosure" and never flagged it. Comprehensive ≠ correct. Tidy ≠ single-purpose.
So, before writing or reviewing a page, name its one type out loud. Then read diataxis.md and hold the page to that type's must / must-not list. Content that belongs to another type gets a one-line cross-link, never an inlined section.
Which file
digraph d {
"Task?" [shape=diamond];
"Authoring or restructuring a page" [shape=box];
"Auditing existing docs" [shape=box];
"Task?" -> "Authoring or restructuring a page" [label="write"];
"Task?" -> "Auditing existing docs" [label="review"];
"Authoring or restructuring a page" -> "diataxis.md";
"Auditing existing docs" -> "audit.md (type purity = Layer 2)";
}
- Authoring / restructuring / splitting →
diataxis.md — the four types, their must/must-not rules, the three-flatland IA mapping, mode-mixing smells, and the split recipe.
- Auditing →
audit.md — the four-layer audit (accuracy, engagement, LLM files, JSDoc). Type purity is Layer 2, criterion #5. Run it in addition to accuracy drift, not instead.
- Supporting reference (loaded as needed by
audit.md): loved-docs-patterns.md, visual-devices.md, react-best-practices.md.
Red flags — STOP and name the type
| Rationalization |
Reality |
| "The page is comprehensive / progressive disclosure." |
A clean layout is not a single purpose. Name the one type; the rest is a split candidate. |
| "It's a task-completion arc." |
That fuses tutorial + how-to + reference. Pick one; link the others. |
| "Splitting causes duplication." |
It doesn't — you cross-link. Each page does one job; the link carries the rest. |
| "One page is more convenient for the reader." |
Convenient to skim, useless to use. The learner, the task-doer, and the looker-up each need a different page. |
| "A reference table fits naturally in this how-to." |
Then the table belongs on the Reference/API page; link to it. A how-to shows the one call you need, not every option. |
These all mean: stop, name the page's single type, and move other-type content out per diataxis.md.
Source: thejustinwalsh/three-flatland — distributed by TomeVault.
1---2name: documentation-853description: Use when authoring, restructuring, splitting, or auditing any docs page or content collection in this repo — choosing what type a page should be, deciding what belongs on it, or checking accuracy, structure, and completeness before a release.4---56# Documentation78Docs are part of the product. This skill governs their **structure and quality**; for the *voice* of the prose, **REQUIRED SUB-SKILL: marketing-voice**.910## The backbone rule1112**Every page is exactly ONE Diátaxis type — tutorial, how-to, reference, or explanation. A page that serves four needs serves none.**1314This is the defect agents miss most, because a clean layout *hides* it. Both observed baselines failed here: an authoring agent fused explanation + a "quick-start arc" + four reference tables into one page and called it a "task-completion arc"; an audit agent praised the same fusion as "progressive disclosure" and never flagged it. Comprehensive ≠ correct. Tidy ≠ single-purpose.1516So, before writing or reviewing a page, **name its one type out loud.** Then read `diataxis.md` and hold the page to that type's must / must-not list. Content that belongs to another type gets a one-line **cross-link**, never an inlined section.1718## Which file1920```dot21digraph d {22 "Task?" [shape=diamond];23 "Authoring or restructuring a page" [shape=box];24 "Auditing existing docs" [shape=box];25 "Task?" -> "Authoring or restructuring a page" [label="write"];26 "Task?" -> "Auditing existing docs" [label="review"];27 "Authoring or restructuring a page" -> "diataxis.md";28 "Auditing existing docs" -> "audit.md (type purity = Layer 2)";29}30```3132- **Authoring / restructuring / splitting** → `diataxis.md` — the four types, their must/must-not rules, the three-flatland IA mapping, mode-mixing smells, and the split recipe.33- **Auditing** → `audit.md` — the four-layer audit (accuracy, engagement, LLM files, JSDoc). Type purity is Layer 2, criterion #5. Run it *in addition to* accuracy drift, not instead.34- Supporting reference (loaded as needed by `audit.md`): `loved-docs-patterns.md`, `visual-devices.md`, `react-best-practices.md`.3536## Red flags — STOP and name the type3738| Rationalization | Reality |39|---|---|40| "The page is comprehensive / progressive disclosure." | A clean layout is not a single purpose. Name the one type; the rest is a split candidate. |41| "It's a task-completion arc." | That fuses tutorial + how-to + reference. Pick one; link the others. |42| "Splitting causes duplication." | It doesn't — you cross-link. Each page does one job; the link carries the rest. |43| "One page is more convenient for the reader." | Convenient to skim, useless to *use*. The learner, the task-doer, and the looker-up each need a different page. |44| "A reference table fits naturally in this how-to." | Then the table belongs on the Reference/API page; link to it. A how-to shows the *one* call you need, not every option. |4546These all mean: stop, name the page's single type, and move other-type content out per `diataxis.md`.4748---49> Source: [thejustinwalsh/three-flatland](https://github.com/thejustinwalsh/three-flatland) — distributed by [TomeVault](https://tomevault.io).50<!-- tomevault:4.0:skill_md:2026-06-15 -->
tomevault-io