56 lines
1.7 KiB
Markdown
56 lines
1.7 KiB
Markdown
---
|
|
name: diataxis-docs
|
|
description: >-
|
|
Classify and structure documentation by Diataxis (tutorial, howto, reference,
|
|
explanation) with PARA status, using frontmatter that the knowledge-base index
|
|
reads. Use when creating a document, when one file tries to do two jobs, or when
|
|
auditing a docs folder.
|
|
---
|
|
|
|
# diataxis-docs
|
|
|
|
Every markdown file answers exactly one of four questions. A file that answers
|
|
two should be split; that is the whole method.
|
|
|
|
| Type | Answers | Reader is |
|
|
|------|---------|-----------|
|
|
| `tutorial` | "teach me by doing" | learning |
|
|
| `howto` | "help me do this task" | working |
|
|
| `reference` | "tell me the facts" | looking up |
|
|
| `explanation` | "help me understand why" | studying |
|
|
|
|
## Frontmatter
|
|
|
|
```yaml
|
|
---
|
|
type: reference # one of the four above
|
|
status: current # current | archive (PARA)
|
|
related:
|
|
- docs/OPS.md
|
|
---
|
|
```
|
|
|
|
`bin/kb/index` reads this. `type` becomes a searchable column and `related`
|
|
becomes a graph edge:
|
|
|
|
```bash
|
|
bin/kb/search search "deploy" --type howto
|
|
bin/kb/search search "Stecktafel" --hop 1 # follow links and related
|
|
```
|
|
|
|
## Audit checklist
|
|
|
|
1. Does the title match the type? A reference that starts "first, open..." is a
|
|
howto wearing a disguise.
|
|
2. More than one H2 topic that a reader would search separately? Split the file.
|
|
The indexer chunks on H2, so split files also search better.
|
|
3. Is `status: archive` set on anything superseded? Archived files stay indexed
|
|
but stop competing with current ones for a reader's attention.
|
|
4. Does every explanation link the reference it explains, and vice versa? That
|
|
link is what `--hop 1` walks.
|
|
|
|
## Rule
|
|
|
|
Do not invent a fifth type. If a document does not fit, it is usually two
|
|
documents.
|