Documentation Diataxis And Technical Writing

Pack: documentation Source: documentation/documentation-diataxis-and-technical-writing/SKILL.md 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

Verification checklist

• one primary doc type is obvious within 10 seconds
• the audience and entry assumptions are explicit
• off-type content is cut, moved, or linked out
• headings support scanning for the intended reader
• examples match the page goal instead of showing everything
• the page has fewer responsibilities than before

Output Shape

When answering with this skill, prefer:

• recommended primary doc type
• target audience and assumptions
• current structural problems
• proposed outline
• cut, move, and link recommendations
• one short rewritten section or heading example

Good Triggers

• documentation, docs structure, mixed README, tutorial vs how-to, reference docs, explanation page, Diataxis, technical writing