| name | document-generate |
| description | Audit existing docs against the four Diataxis quadrants, identify empty quadrants, and generate missing documentation from scratch. Each generated doc serves its quadrant's specific user need. |
When To Use
- When
/document-release reveals entire Diataxis quadrants that are empty for key subsystems.
- When a new subsystem has shipped with zero documentation in any quadrant.
- When the user says "write the docs for X" or "we need documentation for this."
- When a subsystem is being handed off and docs are needed for the receiving team.
- When CI enforces a documentation coverage gating rule that the repo currently fails.
Related: /document-release for release-triggered doc updates and Diataxis coverage mapping; /docs-sync for continuous alignment of existing docs; /domain-context for shared glossary that docs should reference.
Do not use this skill when docs exist and just need updates (use /docs-sync or /document-release), for non-technical prose (marketing, blog posts, brand narrative), or when the audience and use case for the doc are not yet defined.
Core Stance
- Every Diataxis quadrant serves a different user need. A codebase with only reference docs has no onboarding path. A codebase with only tutorials has no depth.
- Generate for the quadrant, not generically. A tutorial is step-by-step and assumes nothing. A reference is comprehensive and assumes competence. A how-to is task-oriented. An explanation provides context.
- Docs are written for the next engineer at 3am. Explicit commands, expected outputs, failure signatures, and troubleshooting steps.
- Every generated doc must include: audience statement (who is this for?), prerequisite list (what must they already know?), and usage context (when to read this vs another doc).
Research Backing
- Procida (2017), Diátaxis: A Systematic Framework for Technical Documentation — four-mode taxonomy with distinct conventions per quadrant: tutorials are learning-oriented and sequential; how-tos are task-oriented and can be read out of order; reference is descriptive and neutral; explanation is discursive and provides context.
- Google Technical Writing Courses — audience-first documentation methodology: define the reader persona before writing; write for the reader who doesn't have the context the writer has.
- Aghajani et al. (2019, IEEE/ACM MSR), Software Documentation Issues Unveiled — incomplete documentation (missing quadrants) is as harmful as incorrect documentation for onboarding and maintenance tasks.
Process
-
Audit existing docs against the four quadrants
- Inventory all existing docs for the target subsystem.
- For each doc: classify which Diataxis quadrant(s) it serves.
- Quadrants:
- Tutorials — learning-oriented, step-by-step, takes reader from zero to basic competence. Sequential, must be read in order.
- How-to guides — task-oriented, solves a specific problem. Assumes basic competence. Can be read out of order.
- Reference — information-oriented, describes the machinery. Accurate, complete, neutral. Designed for consultation, not reading.
- Explanation — understanding-oriented, explains why and how. Provides background, context, design rationale.
- The same doc can serve multiple quadrants — note partial coverage.
-
Identify empty quadrants
- For each empty quadrant: define the audience and use case.
- Tutorial audience: "An engineer new to this subsystem who needs to complete their first task."
- How-to audience: "An engineer who knows the subsystem basics and needs to solve a specific problem."
- Reference audience: "An engineer who needs to look up a specific API, config option, or behavior."
- Explanation audience: "An engineer who needs to understand why the subsystem works the way it does."
-
Prioritize which empty quadrants to generate
- Priority 1: Tutorials (no onboarding path for any subsystem is a blocker).
- Priority 2: Reference (no lookup path means engineers reverse-engineer from source).
- Priority 3: How-to guides (common task patterns that generate repeated questions).
- Priority 4: Explanation (ADRs and design docs may already cover this partially).
-
Generate tutorial drafts
- Structure: "Goal: by the end, you'll have [specific outcome]." Steps numbered. Every step includes the exact command and expected output. Troubleshooting at each step. Prerequisites listed first.
- Length: complete a tutorial in ≤30 minutes. If longer, split into multiple tutorials.
-
Generate reference drafts
- Structure: exhaustive listings. API reference: endpoint, method, params, response, errors, example. Config reference: key, type, default, description, example. CLI reference: command, flags, exit codes, examples.
- Format: designed for
Ctrl+F lookup. Dense, scannable, no narrative.
-
Generate how-to drafts
- Structure: "Problem: [specific task]." Prerequisites. Steps. Expected result. Troubleshooting. Alternative approaches.
- Each how-to is self-contained — no "see tutorial step 3 first."
-
Generate explanation drafts
- Structure: context, design rationale, trade-offs, alternatives considered, historical decisions. Links to ADRs and relevant PRs.
- Narrative, not bullet-list. Explains why, not just what.
-
User review and finalize
- Present drafts for user review. Flag any sections that need owner confirmation (
[NEEDS OWNER CONFIRMATION]).
- After approval: finalize, save to
docs/, update the Diataxis coverage map.
-
Report with generated docs, quadrant coverage before/after, and any remaining gaps.
Operating Rules
- Never generate docs without first auditing existing coverage. The audit is mandatory.
- Tutorials must be end-to-end verifiable — the writer should be able to follow the steps and get the described outcome.
- Reference docs must be comprehensive for the subsystem scope. "Common endpoints only" is not a reference.
- If the subsystem behavior is not yet stable, flag the doc as
[BETA — subject to change] and link to the tracking issue.
- Generated docs must include: audience statement, prerequisite list, and usage context (when to read this doc vs another).
- Never fabricate behavior — if unsure how something works, flag it
[NEEDS OWNER CONFIRMATION] rather than guessing.
- Use the project's existing doc conventions (Markdown flavor, heading style, code block language tags).
Output Format
Return a markdown report with these exact sections:
- Subsystem Scope
- Existing Coverage (before audit — quadrant × doc matrix)
- Empty Quadrants (audience + use case per quadrant)
- Generated Docs (file paths, quadrant, summary, line count)
- Unconfirmed Sections (items marked
[NEEDS OWNER CONFIRMATION])
- Coverage After Generation (updated quadrant × doc matrix)
- Remaining Gaps
- Recommended Next Step
Example
Existing Coverage — Checkout Subsystem
| Doc | Tutorial | How-to | Reference | Explanation |
|---|
docs/api/checkout-openapi.yaml | ✗ | ✗ | ✓ | ✗ |
docs/adr/003-checkout-idempotency.md | ✗ | ✗ | ✗ | ✓ |
Coverage: 2/4 quadrants partially (reference thin — OpenAPI only, no config ref).
Empty Quadrants
- Tutorial: "First checkout integration" — audience: new payment engineer. Use case: get a checkout endpoint working in dev.
- How-to: "Apply a coupon to a checkout" — audience: checkout engineer. Use case: the most common task pattern.
Generated Docs
docs/tutorials/first-checkout-integration.md — Tutorial, 120 lines. Step-by-step: set up dev env → create test cart → call checkout endpoint → verify response.docs/how-to/apply-checkout-coupon.md — How-to, 80 lines. Prerequisites → validate coupon → apply to cart → verify discount in response.docs/reference/checkout-config.md — Reference, 150 lines. Exhaustive config keys, env vars, feature flags, rate limits, error codes.
Coverage After Generation
Coverage: 4/4 quadrants. Tutorial ✓, How-to ✓, Reference ✓, Explanation ✓.
Recommended Next Step
Run /document-release to build the full Diataxis coverage map including the new docs.
