eSlider
63d3be0e19
- bin/db/psql-yq + bin/web/search + tools/{yamlout,websearch} vendored as real files
- bin/db/ssh-tunnel added (OnlyOffice VM pg on 5433)
- skills reference local bin/ paths; no agent-skills/abs links in git
- pyproject.toml + uv.lock; CI installs via uv sync --frozen
- release-please auto-tags semver from conventional commits when green
- LICENSE MIT, badges/mermaid README
1.7 KiB
1.7 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 and related
becomes a graph edge:
bin/kb/search "deploy" --type howto
bin/kb/search "Stecktafel" --hop 1 # follow links and related
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? That
link is what
--hop 1walks.
Rule
Do not invent a fifth type. If a document does not fit, it is usually two documents.