Updated
On this page
Document kinds
The catalog of document kinds, each tied to the question it answers, the stage that produces it and how it is kept up.
Every document is named for the question it answers. The kind appears as the file-name suffix and in the type field. Upkeep describes how the document changes:
- Stable: changes only by a new version.
- Living: edited while work runs.
- Generated: never hand-edited.
- Disposable: working material.
| Kind | Stage | Question it answers | Upkeep |
|---|---|---|---|
| scope | 1 Intake, 2 Route | What do we do, where is the boundary, how do we know it is done, which route? | Living, versioned |
| assessment | 3 | Where are we today, where should we be, what is the gap? | Stable per version |
| research | 3 | What is known outside our system? | Stable |
| findings | 3 or 4 | What did we find, with what evidence and how sure? | Stable per version |
| recommendation | 3 | Which way do we go, and what must you answer? | Stable; frozen on approval |
| outline | 3 | What is the shape of the document? | Living |
| toc | 3 | Which articles will the topic hold? | Living until built |
| inventory | 3 | What exists, exactly? | Stable per version |
| mapping | 3 | Where does each item go? | Stable per version |
| design, spec, architecture | 3 or 4 | What exactly will be made? | Living until built |
| model | 3 or 4 | How is a domain structured? | Living |
| plan | 4 | In what order, who does what? | Living |
| roadmap | 4 | Which phases, what outcome? | Living |
| runbook | 4 or 5 | What do I do when X happens? | Living |
| scout, log, scratch | 4 | What was scanned, tried, logged? | Disposable |
| execution | 4 | What did each run do? | Living |
| verification | 5 | Did the result meet the definition of done, on what evidence? | Stable per run |
| audit | 5 | How does it compare against a standard? | Stable per run |
| results, overview, dashboard | 5 | Where does the work stand? | Generated |
| retrospective | 5, at the end | What did we expect, what happened, what do we change? | Stable |
| tracker | 4, 5 | What is built versus planned? | Generated |
What is not a kind
- Draft and working are states, and belong in the header.
- A home page for a knowledge topic is generated by the knowledge-base build.
- Note and report remain allowed only when no kind fits. The first line must then state the question answered. If the word before "note" is itself a kind, that word is the kind.
Where a decision goes
A decision is made at stage 3 or at a gate in stage 5. It is recorded in the approved recommendation, which is then frozen, with a link to the follow-on work. "Decision" is a term, not a new kind.
Fields for each kind are on Frontmatter by kind.