eSliderandGitHub
c1ee920b0a
Tests / Test (push) Skipped
Tests / Release (semver) (push) Skipped
Commands live at bin/brain/{index,get,stats,eval,watch}.go and
bin/mail/import.go, bin/markdown/import.go, bin/postgres/query.go.
Python remains the Ladybug write worker. index_mail is a deprecation
shim that rebuilds via --with-mail.
54 lines
1.6 KiB
Markdown
54 lines
1.6 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/brain/index.go` reads this. `type` becomes a searchable column. `related:` is
|
|
frontmatter for humans; graph hops from it are not implemented yet.
|
|
|
|
```bash
|
|
bin/brain/search.go "deploy"
|
|
```
|
|
|
|
## 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?
|
|
|
|
## Rule
|
|
|
|
Do not invent a fifth type. If a document does not fit, it is usually two
|
|
documents.
|