eSliderandGitHub
1c7db6d499
Published docs and skills still taught bin/kb/search --hop 1. Search lives at bin/brain/search.go; --hop errors until File edges exist. A unittest gates the SoT so the lie cannot return.
1.6 KiB
1.6 KiB
name, description
| name | description |
|---|---|
| diataxis-docs | 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
---
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. related: is
frontmatter for humans; graph hops from it are not implemented yet.
bin/brain/search.go "deploy"
Audit checklist
- Does the title match the type? A reference that starts "first, open..." is a howto wearing a disguise.
- 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.
- Is
status: archiveset on anything superseded? Archived files stay indexed but stop competing with current ones for a reader's attention. - 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.