| name | diataxis |
| description | Author user-facing technical documentation following the Diataxis framework — tutorials, how-to guides, reference material, and conceptual explanations. Picks the right of the four documentation modes for the request, applies that mode's structural template, and avoids cross-mode bleed (no comprehensive API listings inside a tutorial, no learning exercises inside reference docs, no step-by-step procedures inside an explanation). Use whenever someone asks to document something for users, write a getting-started guide, generate an API or config or CLI reference, write a deployment / migration / troubleshooting guide, explain a design decision, or produce any docs that will live in `docs/`. Trigger phrases include "write a tutorial", "create a how-to", "document the API", "explain why we chose", "generate config docs", "build a reference", "write user docs for X", and any open-ended request to produce user-facing documentation. Not for: README content, code comments, architecture / C4 / ADR / OpenAPI work (use `aeo-docs:architecture-docs` instead), or internal design docs that aren't user-facing.
|
Diataxis — User-Facing Documentation
The Diataxis framework splits user-facing documentation into four modes that serve different reader needs. Most "bad documentation" comes from mixing modes — a tutorial that gets reference-dumpy, a reference that wanders into design rationale, a how-to that pauses to teach concepts. Pick the mode first; the template flows from that.
The four modes
| Mode | Reader is | Reader wants | Output is |
|---|
| Tutorial | a beginner | to learn by doing | a guided practice exercise |
| How-to guide | competent | to solve a specific problem | a goal-oriented procedure |
| Reference | already knows what they need | to look up exact specifications | comprehensive, scannable lookup |
| Explanation | experienced | to understand why | a conceptual narrative |
The reader's state and intent decide the mode, not the topic. The same feature can have all four — a tutorial that walks a beginner through using it, a how-to that solves a specific problem with it, a reference that lists every option, and an explanation of why it works the way it does.
Picking the mode
Two questions resolve the choice:
- Is the reader trying to learn, or trying to do something specific? Learning → tutorial or explanation. Doing → how-to or reference.
- Is the reader hands-on, or after concepts? Hands-on → tutorial (learning) or how-to (doing). Conceptual → explanation (learning) or reference (doing).
hands-on conceptual
┌───────────────────┬──────────────────┐
learning │ Tutorial │ Explanation │
├───────────────────┼──────────────────┤
doing │ How-to │ Reference │
└───────────────────┴──────────────────┘
When a request fits multiple modes, write multiple short docs rather than one cross-mode doc. A "guide to X" that's three modes glued together helps no one.
Mode summaries — read the matching reference for the full template
Tutorial — "build your first X"
Beginner-safe, hands-on, single linear path, every step verified. The reader follows along; the doc holds their hand. Goal is confidence and basic familiarity, not comprehensive knowledge.
→ Output: docs/tutorials/. Read references/tutorial.md for the section template, anti-patterns, and quality checklist.
How-to guide — "how to X in Y"
Goal-oriented procedure for someone who already knows the basics. Imperative voice ("Set", "Configure", "Run"), real-world conditions, troubleshooting included. Shortest reasonable path from problem to solution.
→ Output: docs/how-to/. Read references/howto.md for the section template.
Reference — "the X API / config / CLI"
Comprehensive, factual, scannable. Reader knows what they need; the doc tells them exactly. No tutorials, no opinions, no design rationale — those live elsewhere and get linked.
→ Output: docs/reference/. Read references/reference.md for the API, config, CLI, schema, and error-code templates (different reference types have different shapes).
Explanation — "why X works this way"
Builds mental models. Discusses trade-offs, alternatives, history, and design rationale. The reader should come away thinking differently about the system, not knowing how to do something new.
→ Output: docs/explanation/. Read references/explanation.md for the section template.
Output conventions across all four modes
File paths
docs/
├── tutorials/ # Tutorial mode
├── how-to/ # How-to mode
├── reference/ # Reference mode
└── explanation/ # Explanation mode
If the project doesn't have a docs/ tree yet, create the relevant subdirectory the first time you write into it. Don't create empty siblings preemptively — they accrete cruft.
File naming
Kebab-case, lead with the verb or topic noun:
| Mode | Examples |
|---|
| Tutorial | getting-started-[tool].md, build-[thing].md, learn-[concept].md, connect-[a]-to-[b].md |
| How-to | configure-[feature].md, integrate-[system].md, troubleshoot-[problem].md, migrate-[from]-to-[to].md, deploy-[target].md |
| Reference | [component]-api.md, [feature]-config.md, [tool]-cli.md, [data]-schema.md, error-codes.md |
| Explanation | [concept]-design.md, [system]-architecture.md, understanding-[topic].md, [pattern]-explained.md |
Cross-linking
Each mode links out to the other three when the reader's next question would be better served there. The four-way footer is a good default at the end of any doc:
## See also
- **Want to follow along?** → `../tutorials/<topic>.md`
- **Solving a specific problem?** → `../how-to/<task>.md`
- **Looking up specs?** → `../reference/<component>.md`
- **Want to understand why?** → `../explanation/<concept>.md`
Drop bullets that don't have a corresponding doc on the other end — broken-link rot is worse than a shorter footer.
Cross-mode anti-patterns — fingerprints of mode bleed
These are the patterns that mean you've drifted out of mode. If you catch yourself writing one, stop and ask whether the content belongs in a different doc.
| Drift | Fingerprint | Fix |
|---|
| Tutorial → reference | Listing every option of a thing the reader is just trying to use once | Pick one good default, link to the reference for the rest |
| How-to → tutorial | Pausing to teach basics the audience should already know | State the prereqs, link to a tutorial |
| Reference → explanation | Design rationale interleaved with specs | Keep the reference factual, push rationale into an explanation doc |
| Explanation → how-to | Step-by-step instructions creeping into the conceptual narrative | Link to a how-to for the procedure |
When the request is ambiguous
Common cases and how to resolve them:
- "Document X" with no other context — if X is an API / config / CLI, default to a reference. Otherwise ask whether the audience is learning or already using it. When unclear, a how-to plus a reference covers most needs without writing a tutorial nobody asked for.
- "Write docs for the new feature" — almost always means at least a how-to (for users who'll adopt it) plus a reference (for the spec). A tutorial only if the feature is a new entry point users learn from scratch.
- "Explain how X works" is ambiguous between how-to and explanation. "How does it work" (mechanism) → explanation. "How do I use it" (procedure) → how-to. Ask if you can't tell from context.
- "Add a section to existing docs" — match the mode of the existing doc; don't introduce a different mode mid-page.
Diagrams in docs
For diagrams inside any of the four modes:
- Mermaid (flowcharts, sequence diagrams, class diagrams, gantt) →
aeo-docs:markdown-mermaid skill. Renders natively on GitHub and most MD viewers.
- D2 (architecture, sequence_diagram, sql_table, class, grid, c4 — the full Terrastruct DSL) →
aeo-docs:d2 skill. More powerful, requires the d2 CLI to render to SVG/PNG.
For C4 architecture / ADR / OpenAPI work, that's a different kind of documentation entirely — use the aeo-docs:architecture-docs skill, not Diataxis.
Why this skill exists
The four-mode separation is the substance. The voice differences (encouraging in tutorials, terse in how-tos, factual in references, thoughtful in explanations) fall out of the mode choice — once you've picked the right mode, the right register comes with it. Writing in mode is more about what not to include than what to add.
