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.

| Need | Recommended Approach |
|------|---------------------|
| Write a specific document | Use content type rules (`write-` prefix) + templates |
| Plan documentation strategy | Use architecture rules (`arch-` prefix) + adoption funnel |
| Audit existing documentation | Use audit rules (`audit-` prefix) + maturity model |
| Improve writing quality | Use style rules (`style-` prefix) |
| Set up docs-as-code | Use architecture rules (`arch-` prefix) |
| Build partner documentation | Use DX rules (`dx-` prefix) |
| Migrate/version documentation | Use governance rules (`gov-` prefix) |

## Foundational Frameworks

| Framework | Contribution | Source |
|-----------|-------------|--------|
| **Diataxis** | Content architecture — the four quadrants | diataxis.fr |
| **Google OpenDocs** | Project archetypes, maturity assessment, audit | github.com/google/opendocs |
| **Good Docs Project** | Content type templates with writing guides | thegooddocsproject.dev |
| **Google Style Guide** | Language, tone, and formatting standards | developers.google.com/style |
| **Stripe DX Patterns** | Outcome-oriented docs, developer journey design | docs.stripe.com |
| **Canonical Practice** | Documentation as engineering discipline | canonical.com/documentation |

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Content Architecture | CRITICAL | `write-` (6 rules) |
| 2 | Writing Style | CRITICAL | `style-` (6 rules) |
| 3 | Information Architecture | HIGH | `arch-` (4 rules) |
| 4 | Developer Experience | HIGH | `dx-` (3 rules) |
| 5 | Documentation Audit | MEDIUM | `audit-` (3 rules) |
| 6 | Governance & Lifecycle | MEDIUM | `gov-` (3 rules) |
| 7 | Partner & Ecosystem | MEDIUM | `partner-` (2 rules) |

## 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

| Content Type | Quadrant | When to Use |
|-------------|----------|-------------|
| **Tutorial** | Learning | New users need guided first experience |
| **Quickstart** | Learning + Task | Experienced devs need fast path to "hello world" |
| **How-to Guide** | Task | Users need to accomplish specific goals |
| **Integration Guide** | Task | Partners need to connect their systems |
| **Migration Guide** | Task | Users need to upgrade between versions |
| **Troubleshooting** | Task | Users need to diagnose and fix problems |
| **API Reference** | Information | Developers need exact specifications |
| **SDK Reference** | Information | Developers need language-specific details |
| **Configuration Reference** | Information | Operators need parameter details |
| **Changelog** | Information | Users need to track what changed |
| **Explanation** | Understanding | Users need to understand "why" |
| **Architecture Guide** | Understanding | Engineers need system design context |
| **Glossary** | Information | Everyone needs consistent terminology |
| **Runbook** | Task | Operators need incident response procedures |

## Audience Matrix

| Audience | Primary Need | Key Content Types |
|----------|-------------|-------------------|
| **New developers** | Get started quickly | Quickstart, Tutorial |
| **Building developers** | Complete tasks efficiently | How-to guides, API reference |
| **Evaluating developers** | Decide whether to adopt | Explanation, Architecture |
| **Partner integrators** | Connect their systems | Integration guide, SDK reference |
| **Internal engineers** | Operate and maintain | Runbook, Architecture, Config reference |
| **Decision makers** | Understand capabilities | Explanation, Architecture overview |

## 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:

| Project Type | When to Use |
|-------------|-------------|
| **The Manual** | Writing new user/developer/admin guides from scratch |
| **The Edit** | Improving existing docs for accuracy, style, or goals |
| **The Audit** | Reviewing existing docs to assess condition and gaps |
| **The Migration** | Changing docs infrastructure (platform, format, hosting) |
| **The Factory** | Setting up automation, CI/CD, and tooling for docs |
| **The Translation** | Internationalizing and localizing documentation |
| **The Rules** | Creating contributor guidelines and style standards |
| **The Study** | Investigating user needs and documentation usage patterns |

## The Diataxis Map

| | Tutorials | How-to Guides | Reference | Explanation |
|-|-|-|-|-|
| **What they do** | Introduce, educate, lead | Guide | State, describe, inform | Explain, clarify, discuss |
| **Answers** | "Can you teach me to...?" | "How do I...?" | "What is...?" | "Why...?" |
| **Oriented to** | Learning | Goals | Information | Understanding |
| **Purpose** | Provide a learning experience | Help achieve a goal | Describe the machinery | Illuminate a topic |
| **Form** | A lesson | A series of steps | Austere description | Discursive explanation |
| **Analogy** | Teaching a child to cook | A recipe in a cookbook | Info on a food packet | Article on culinary history |

## 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.

| Style | Best For | Key Difference from Default |
|-------|----------|----------------------------|
| **Diataxis** (default) | Any project | Per-quadrant tone: "we" in tutorials, impersonal in reference, opinionated in explanation |
| **Google** | Open source, Google ecosystem | Always "you", uniform conversational tone, strict word list, accessibility-first |
| **Microsoft** | Enterprise B2B, internal platforms | Warm brand voice everywhere, bias-free communication, UI text conventions |
| **Stripe** | API-first products, DX-focused | Outcome-first framing, three-column layout, interactive code, docs as product |
| **Canonical** | Infrastructure, open source platforms | Pure Diataxis + engineering discipline, four pillars framework, starter packs |
| **Minimal** | Startups, MVPs, internal tools | README-first, auto-generate what you can, ship without perfection |

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

## References

| Priority | Reference | When to read |
|----------|-----------|-------------|
| 1 | `references/content-types.md` | Writing any specific content type — purpose, structure, principles, anti-patterns for all 14 types |
| 2 | `references/templates.md` | Starting a new document — ready-to-use skeletons for tutorials, how-to, API ref, migration, runbook, etc. |
| 3 | `references/style-guide.md` | Making writing decisions — formatting, code examples, accessibility, multi-audience patterns |
| 4 | `references/anti-patterns.md` | Reviewing documentation — consolidated checklist of documentation smells and common mistakes |
| 5 | `references/enterprise-patterns.md` | Planning docs strategy — IA, docs-as-code, versioning, governance, maturity model, metrics, partner docs |
| 6 | `references/styles/diataxis.md` | Default style — per-quadrant voice, person, tone, phrasing patterns for all four Diataxis types |
| 7 | `references/styles/google.md` | Google style override — uniform "you", sentence case, word list, accessibility priority |
| 8 | `references/styles/microsoft.md` | Microsoft style override — warm brand voice, bias-free communication, UI conventions |
| 9 | `references/styles/stripe.md` | Stripe style override — outcome-first, interactive code, docs-as-product culture |
| 10 | `references/styles/canonical.md` | Canonical style override — pure Diataxis + engineering discipline, four pillars |
| 11 | `references/styles/minimal.md` | Minimal style override — README-first, MVP docs, ship fast |

## Ecosystem

This skill works well alongside complementary skills for related workflows:

| Companion Skill | When It Helps |
|----------------|---------------|
| **API design skills** (OpenAPI, Zod) | Generating accurate API reference docs from schemas |
| **Testing skills** (Jest, Vitest) | Writing testable code examples that stay correct |
| **Frontend design skills** | Building interactive documentation sites and sandboxes |
| **Code review skills** | Reviewing documentation PRs for quality and completeness |
| **Git workflow skills** | Managing docs-as-code workflows and PR-based reviews |

## Full Compiled Document

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