Enterprise technical documentation best practices, patterns, and frameworks for developer and partner adoption. Covers content architecture (Diataxis four qu...
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.
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) |
| 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 |
| 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) |
write-one-purpose-per-doc — Never mix content types; tutorials teach, how-to guides solve, reference describes, explanation contextualizeswrite-tutorial-not-howto — Tutorials are learning-oriented (student); how-to guides are task-oriented (practitioner). Most common conflation in docswrite-reference-describe-only — Reference docs describe machinery neutrally; never instruct, explain, or opinewrite-explanation-no-steps — Explanation provides "why" and context; never include step-by-step procedureswrite-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 diagramsstyle-active-voice-second-person — Use active voice and address the reader as "you"; present tense for descriptionsstyle-code-examples-must-work — Every code example must be copy-pasteable and runnable; test examples in CIstyle-consistent-terminology — One term per concept everywhere; never alternate between synonyms for the same thingstyle-global-readability — No idioms, cultural references, or humor that doesn't translate; spell out acronyms on first usestyle-minimize-admonitions — Max 2-3 callouts per page; if everything is a warning, nothing isstyle-tone-matches-type — Tutorials are encouraging; how-to guides are direct; reference is neutral; explanation is conversationalarch-organize-by-type-not-team — Structure docs by content type (guides, reference, tutorials), not by internal team or componentarch-two-level-max — Limit navigation hierarchy to two levels of nesting; deeper structures lose readersarch-adoption-funnel — Prioritize docs that unblock the current adoption bottleneck: Discover → Evaluate → Start → Build → Operate → Upgradearch-cross-link-strategy — Every doc links to prerequisites, related content, and next steps; no dead endsdx-time-to-hello-world — Optimize quickstart for speed; experienced devs should reach a working example in under 5 minutesdx-audience-matrix — Map audiences (new devs, building devs, evaluators, partners, operators, decision makers) to content typesdx-interactive-examples — Provide runnable sandboxes, multi-language code tabs, and copy-pasteable examples wherever possibleaudit-inventory-first — Before improving docs, inventory every page: URL, title, content type, owner, last updated, accuracyaudit-classify-and-gap — Classify each page into its Diataxis quadrant; identify gaps, overlaps, and misclassificationsaudit-maturity-model — Assess against four maturity levels: Seeds → Foundation → Integration → Excellencegov-docs-are-done — A feature is not shipped until its documentation is written, reviewed, and publishedgov-version-strategy — Version API/SDK docs per major version; don't version conceptual docs unless concepts changegov-freshness-cadence — API reference: matches current release; how-to guides: quarterly review; runbooks: review after every incidentpartner-both-sides — Integration guides document both sides of the interaction, not just your APIpartner-production-readiness — Every integration guide includes a production readiness checklist and support escalation pathsEvery 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:
| 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 | 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 |
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
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 |
| 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 |
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.
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.
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:
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 |
| 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.
| 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 |
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 |
For the complete guide with all rules expanded: AGENTS.md
ZIP package — ready to use