documentation-diataxis-and-technical-writing

Documentation Diataxis And Technical Writing

Use this skill when the real problem is doc shape, not missing words.

Scope

• choosing whether a page should be tutorial, how-to, reference, or explanation
• restructuring mixed or confusing docs
• splitting one overloaded page into clearer sibling docs
• tightening audience assumptions, headings, and examples
• improving developer docs, product docs, and internal engineering docs

Not for

• autogenerated API reference
• changelogs or release notes
• marketing copy
• docs that are already narrow, obvious, and structurally correct

Default path

1. State the reader and their immediate need in one sentence.
2. Choose one primary doc type:
   • tutorial when the reader should learn by doing
   • how-to when the reader wants one task completed
   • reference when the reader needs exact facts quickly
   • explanation when the reader needs concepts, rationale, or tradeoffs
3. Rewrite the outline so every section serves that one doc type.
4. Cut, move, or link any content that belongs to a different doc type.
5. Keep headings and examples aligned to the chosen purpose.
6. Make adjacent needs explicit through links instead of stuffing them into the same page.

When to deviate

• A landing page or top-level README can contain a thin mix of orientation and links, but each section should still have a clear role.
• A short how-to may include a tiny reference table if lookup is essential to finishing the task.
• A tutorial can include brief explanation only when it directly unblocks the next step.

Guardrails

• Do not treat Diataxis as taxonomy theater; use it to cut ambiguity.
• Do not mix task flow with long conceptual digressions.
• Do not bury reference facts inside narrative prose.
• Do not assume a beginner audience unless the page is explicitly onboarding.
• Keep examples short and directly tied to the page goal.

Avoid

• one page trying to teach, explain, and act as reference at the same time
• setup sections that become mini tutorials inside a how-to
• long rationale blocks inside lookup-oriented docs
• writing for the vaguest possible audience
• leaving cut content in place just because it is technically useful