Diataxis Docs Framework

Tech Docs

IMPORTANT: Your training data about documentation best practices may be outdated or conflate different frameworks. Diataxis, Google OpenDocs, and the Good Docs Project each have specific structural requirements that are frequently mixed up — especially the critical distinction between tutorials (learning-oriented) and how-to guides (task-oriented). Always rely on this skill's rule files and reference documents as the source of truth. Do not fall back on generic documentation advice when it conflicts with these frameworks.

When to Use This Skill

This skill is for writing, planning, auditing, and improving technical documentation for products that need developer and partner adoption. It synthesizes six proven frameworks into a unified system.

Foundational Frameworks

Rule Categories by Priority

Quick Reference

1. Content Architecture (CRITICAL)

• write-one-purpose-per-doc — Never mix content types; tutorials teach, how-to guides solve, reference describes, explanation contextualizes
• write-tutorial-not-howto — Tutorials are learning-oriented (student); how-to guides are task-oriented (practitioner). Most common conflation in docs
• write-reference-describe-only — Reference docs describe machinery neutrally; never instruct, explain, or opine
• write-explanation-no-steps — Explanation provides "why" and context; never include step-by-step procedures
• write-outcomes-not-features — Document what users achieve ("move data to your warehouse"), not what exists ("the Pipeline object")
• write-show-dont-tell — Every concept needs a concrete example; abstract descriptions become concrete through code and diagrams

2. Writing Style (CRITICAL)

• style-active-voice-second-person — Use active voice and address the reader as "you"; present tense for descriptions
• style-code-examples-must-work — Every code example must be copy-pasteable and runnable; test examples in CI
• style-consistent-terminology — One term per concept everywhere; never alternate between synonyms for the same thing
• style-global-readability — No idioms, cultural references, or humor that doesn't translate; spell out acronyms on first use
• style-minimize-admonitions — Max 2-3 callouts per page; if everything is a warning, nothing is
• style-tone-matches-type — Tutorials are encouraging; how-to guides are direct; reference is neutral; explanation is conversational

3. Information Architecture (HIGH)

• arch-organize-by-type-not-team — Structure docs by content type (guides, reference, tutorials), not by internal team or component
• arch-two-level-max — Limit navigation hierarchy to two levels of nesting; deeper structures lose readers
• arch-adoption-funnel — Prioritize docs that unblock the current adoption bottleneck: Discover → Evaluate → Start → Build → Operate → Upgrade
• arch-cross-link-strategy — Every doc links to prerequisites, related content, and next steps; no dead ends

4. Developer Experience (HIGH)

• dx-time-to-hello-world — Optimize quickstart for speed; experienced devs should reach a working example in under 5 minutes
• dx-audience-matrix — Map audiences (new devs, building devs, evaluators, partners, operators, decision makers) to content types
• dx-interactive-examples — Provide runnable sandboxes, multi-language code tabs, and copy-pasteable examples wherever possible

5. Documentation Audit (MEDIUM)

• audit-inventory-first — Before improving docs, inventory every page: URL, title, content type, owner, last updated, accuracy
• audit-classify-and-gap — Classify each page into its Diataxis quadrant; identify gaps, overlaps, and misclassifications
• audit-maturity-model — Assess against four maturity levels: Seeds → Foundation → Integration → Excellence

6. Governance & Lifecycle (MEDIUM)

• gov-docs-are-done — A feature is not shipped until its documentation is written, reviewed, and published
• gov-version-strategy — Version API/SDK docs per major version; don't version conceptual docs unless concepts change
• gov-freshness-cadence — API reference: matches current release; how-to guides: quarterly review; runbooks: review after every incident

7. Partner & Ecosystem (MEDIUM)

• partner-both-sides — Integration guides document both sides of the interaction, not just your API
• partner-production-readiness — Every integration guide includes a production readiness checklist and support escalation paths

The Documentation Compass

Every document serves one of four fundamental purposes (Diataxis quadrants):

                    PRACTICAL
                       |
         Tutorials     |     How-to Guides
        (learning)     |     (task-oriented)
                       |
   ACQUISITION --------+-------- APPLICATION
                       |
        Explanation    |     Reference
       (understanding) |     (information)
                       |
                   THEORETICAL

Quick classification — ask two questions:

1. Studying or working? Studying → left (tutorials, explanation). Working → right (how-to, reference).
2. Practical steps or theoretical knowledge? Practical → top (tutorials, how-to). Theoretical → bottom (explanation, reference).

Enterprise Content Types

Audience Matrix

Adoption Funnel

Prioritize content types that unblock the current bottleneck:

Discover  → "What is this?"           → Explanation, README
Evaluate  → "Should I use this?"      → Architecture, Comparison
Start     → "How do I begin?"         → Quickstart, Tutorial
Build     → "How do I do X?"          → How-to guides, API reference
Operate   → "How do I keep it going?" → Runbook, Troubleshooting, Config ref
Upgrade   → "How do I move forward?"  → Migration guide, Changelog

Documentation Project Archetypes

When planning documentation work (not single documents), use Google OpenDocs archetypes:

The Diataxis Map

Quality Standards

Diataxis distinguishes two categorically different types of quality:

Functional quality (objective, measurable, independent): Accurate, Complete, Consistent, Current, Precise

Deep quality (subjective, interdependent, conditional on functional quality): Feels good to use, Has flow, Fits human needs, Anticipates the user

Diataxis addresses deep quality — it cannot fix inaccurate content, but it exposes functional quality problems by making them visible when documentation is properly structured.

How to Apply Diataxis

Don't create empty structures. Getting started does not mean dividing docs into four empty sections labeled tutorials/howto/reference/explanation. That's horrible. Diataxis changes structure from the inside.

Work iteratively. Pick any piece of documentation. Ask: what user need does this serve? How well? What one change would improve it? Do it. Repeat. Small, responsive iterations over top-down planning.

Complete, not finished. Like a living plant, your documentation is never finished (it can always grow) but always complete (nothing is missing at this stage of growth). Every stage from seed to mature tree is whole.

How to Use

Read individual rule files for detailed explanations and examples:

rules/write-one-purpose-per-doc.md
rules/style-active-voice-second-person.md
rules/arch-adoption-funnel.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect example with explanation
• Correct example with explanation
• Additional context and decision tables

Writing Style System

This skill supports pluggable writing styles. The default is Diataxis style — per-quadrant tone that matches each content type's purpose. Override with a specific organization's conventions when needed.

Default: Diataxis style (loaded automatically). Each quadrant has its own voice, person, and tone.

To apply a style override, read references/styles/[style].md and follow its divergences from the default.

References

Ecosystem

This skill works well alongside complementary skills for related workflows:

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md