diataxis-writer

name

diataxis-writer

description

Write, restructure, classify, and review documentation using the Diataxis framework. Use this skill whenever the user asks to create, improve, audit, or reorganize docs, documentation, knowledge bases, help centers, onboarding guides, internal process docs, manuals, runbooks, product docs, API/developer docs, tutorials, how-to guides, references, or explanations. Also use it when the user mentions Diataxis, tutorial, how-to, reference, explanation, docs taxonomy, documentation architecture, or asks why a document feels confusing. Do not use it for marketing copy, legal contracts, fiction, sales proposals, press releases, or persuasion-first writing unless the user explicitly wants a Diataxis-style documentation analysis.

Diataxis Writer

Use Diataxis to align documentation with the reader's actual need. The framework is not just a set of templates; it is a way to keep four different user jobs from getting mixed into one confusing document.

Explaining Diataxis to Users

When the user asks what Diataxis is, why it matters, or why this framework is a good fit, explain it briefly before applying it:

Diataxis is a documentation framework that separates docs by the reader's mode of work: learning, doing, looking up facts, or understanding concepts. This matters because readers come to documentation with different expectations. A beginner following a tutorial needs a guided path; an operator fixing a production issue needs direct steps; a developer checking an API needs precise reference; a team making architectural decisions needs explanation and tradeoffs. Mixing these jobs into one page makes docs feel long, unclear, and hard to maintain.

Use these benefits when recommending Diataxis:

• It clarifies what each document is for before writing begins.
• It reduces bloated "everything pages" by separating learning, task execution, lookup, and conceptual understanding.
• It improves reader experience because the structure matches the reader's goal.
• It makes documentation sets easier to maintain because each page has a clear promise and ownership boundary.
• It works beyond technical docs for knowledge bases, onboarding material, internal process docs, manuals, and operational guides, as long as the content is meant to help people learn, do, look up, or understand something.

Do not oversell Diataxis as universal. It is less suitable for persuasion-first writing such as marketing pages, sales proposals, press releases, legal contracts, or fiction unless the user explicitly wants a Diataxis-style critique.

Core Model

Classify the document by the reader's intent:

Reader need	Diataxis type	Document promise
Learn by doing	Tutorial	"Follow this path and you will gain basic competence."
Complete a task	How-to guide	"Follow these steps to achieve this outcome."
Look up facts	Reference	"Find accurate, complete information quickly."
Understand context	Explanation	"Understand why something works this way."

If the user asks for detailed templates, transformation patterns, or examples, read references/diataxis-patterns.md.

Workflow

1. Identify the reader's job. Decide whether the reader is trying to learn, do, look up, or understand. If the request is ambiguous, state the most likely classification and proceed unless choosing incorrectly would change the whole deliverable.
2. Define audience and scope. Capture reader level, product/process context, desired outcome, and constraints. Keep these visible while writing.
3. Choose one primary document type. Let the primary type control structure, tone, and depth. Supporting material from other types should be moved to a short "Related" section or a separate document.
4. Write or restructure around the promise. Use the type-specific guidance below. Avoid blending tutorial, how-to, reference, and explanation into one page just because the information is related.
5. Verify the result. Check that each section helps the primary reader job. Remove or relocate sections that serve a different job.

Type Guidance

Tutorial

Use a tutorial when the reader needs a guided learning experience.

• Give the reader a safe, repeatable path from zero to a concrete result.
• Prefer one reliable route over a catalog of options.
• Include enough explanation to keep the learner oriented, but do not interrupt the lesson with deep theory or exhaustive reference material.
• Make success visible with checkpoints, expected outputs, and recovery notes.
• Avoid assuming the reader can make expert decisions before the lesson teaches the relevant concepts.

How-to Guide

Use a how-to guide when the reader already has context and wants a task done.

• Start with the outcome, prerequisites, and when to use the guide.
• Write action-oriented steps in the order the user should perform them.
• Include decision points, warnings, rollback/recovery guidance, and verification.
• Keep conceptual background brief; link to explanations when the "why" would distract from completing the task.
• Avoid turning the guide into a beginner lesson.

Reference

Use reference when the reader needs accurate lookup material.

• Organize by the natural structure of the subject: commands, fields, endpoints, options, states, errors, schemas, components, policies, or glossary terms.
• Be complete, consistent, and predictable. Reference users scan; they do not want narrative buildup.
• Use tables, signatures, examples, defaults, limits, and cross-references.
• Keep interpretation minimal. If the reader needs rationale, link to an explanation.

Explanation

Use explanation when the reader needs understanding, context, or rationale.

• Explain concepts, mental models, design decisions, tradeoffs, history, and consequences.
• Prefer clear prose, diagrams, comparisons, and examples over procedural steps.
• Show why alternatives exist and why one choice was made.
• Do not promise task completion. If the reader needs steps, link to a how-to.

Mixed Documents

Real documentation sets often need all four types, but a single page should still have one dominant job. When a page mixes types:

1. Name the dominant reader need.
2. Extract unrelated material into separate pages or clearly marked sections.
3. Add links between the pages so readers can move from learning to doing, from doing to lookup, or from lookup to understanding.

Useful split patterns:

• A long "getting started" page often becomes a tutorial plus a reference page.
• A troubleshooting article often becomes a how-to guide plus an explanation of the underlying failure mode.
• A product overview often becomes an explanation plus task-specific how-to guides.
• API docs often become reference pages with separate tutorials and how-to guides.

Helper Script

Use the classifier as a quick heuristic when reviewing an existing document. It does not replace editorial judgment, but it can surface mixed signals quickly.

Run it from the skill directory:

bash ./scripts/classify-doc.sh path/to/doc.md

The script also accepts stdin:

cat path/to/doc.md | bash ./scripts/classify-doc.sh

Output Format

When writing a new document, return:

1. A brief classification note: document type, reader job, and key assumption.
2. The document itself.
3. A short verification checklist if the task involves review, restructuring, or a high-stakes knowledge base.

When reviewing an existing document, return:

1. Current dominant Diataxis type.
2. Mixed-type problems, with section-level examples.
3. Recommended target structure.
4. Concrete rewrite plan or rewritten sections, depending on the user's request.

Quality Checklist

• The page has one primary reader job.
• The title and opening promise match that reader job.
• Tutorial content teaches through doing instead of explaining everything first.
• How-to content helps a competent reader finish a task without detours.
• Reference content is complete, scannable, and consistently structured.
• Explanation content develops understanding without pretending to be a procedure.
• Related-but-different material is linked or separated rather than blended.
• The output matches the user's language unless they request otherwise.