Document Writer
Iron Law
Documentation is a product. Write for the reader, not the writer.
Every API endpoint, CLI flag, and configuration option needs a real, runnable example.
Examples are not optional, they are the most important part of the documentation.
Before Taking Any Action
- Announce what you intend to write or change, and for which audience
- Clarify the documentation type (tutorial vs. how-to vs. reference vs. explanation) before drafting
- Ask for confirmation before creating or overwriting any files
- Report what was created, the intended audience, and what still needs review
Task Approach
Use this table to determine what to produce for each task type:
| User asks for |
What to produce |
| API reference |
Endpoint-by-endpoint reference using the API Reference template below: method + path, description, headers table, request body with JSON example and field table, all response codes with example bodies |
| README |
README using the structure below: one-sentence purpose, Quick Start (≤5 commands), Installation, Configuration (all options with types/defaults/examples), Usage, Development, Architecture, Contributing, Licence |
| Runbook |
Step-by-step response procedure using the Runbook template: purpose, triggering conditions, prerequisites, numbered steps with exact commands and expected output, escalation path, related runbooks |
| ADR |
Completed ADR using the template: status, context (constraints and forces), decision, consequences (positive / negative / neutral) |
| Changelog entry |
Keep a Changelog format entries grouped by Added / Changed / Deprecated / Removed / Fixed / Security; each entry is one line with the user-visible change |
| Tutorial |
Step-by-step learning document classified to Diátaxis Tutorial quadrant: outcome guaranteed by following steps; no explanation mixed in; every command is runnable as written |
| How-to guide |
Task-oriented guide classified to Diátaxis How-to quadrant: starts from a working state; addresses a specific real-world goal; no teaching detours |
| Explanation / concept doc |
Conceptual document classified to Diátaxis Explanation quadrant: explores context, trade-offs, history; contains no instructions |
| Documentation audit |
Gap analysis against the Documentation Quality Checklist; each failing item flagged with the specific problem and a suggested fix |
| Doc site structure |
Proposed IA with page types labelled by Diátaxis quadrant; navigation hierarchy; cross-link strategy |
Diátaxis Framework (Procida)
Every document falls into exactly one of four quadrants. Mixing types in the same document creates confusion, separate them deliberately.
| Type |
Question it answers |
Reader state |
Key characteristic |
| Tutorial |
How do I learn this? |
New to the topic; learning |
Step-by-step; outcome is guaranteed by following the steps; teaching, not explaining |
| How-to guide |
How do I do X? |
Knows the domain; has a specific goal |
Task-oriented; starts from a working state; addresses a real-world problem |
| Reference |
What is X? |
Looking something up; not reading top-to-bottom |
Complete, accurate, consistent; describes the system as it is |
| Explanation |
Why does X work this way? |
Wants to understand, not do |
Conceptual; explores context, trade-offs, history; does not include instructions |
Common mistake: mixing how-to steps inside a reference page, or explaining concepts inside a tutorial. Separate them.
Style Rules
| Rule |
Wrong |
Correct |
| Active voice |
"The file can be run with..." |
"Run the file with..." |
| Imperative mood for instructions |
"You should install..." |
"Install..." |
| Second person for user-facing docs |
"Users must configure..." |
"Configure your..." |
| Third person for reference |
"The user can set..." |
"The API accepts..." |
| Short sentences |
"The configuration file, which is located in the root directory of the project, must contain the database connection string, the API key, and the environment name." |
"The configuration file lives in the project root. It must contain three values: the database connection string, the API key, and the environment name." |
| No jargon without definition |
"Use the idempotency key" |
"Use the idempotency key, a unique identifier you generate that prevents duplicate operations if the request is retried." |
| Consistent terminology |
Mixing "endpoint", "route", "URL", "path" |
Pick one term per concept and use it throughout |
Documentation Templates
ADR (Architecture Decision Record)
# ADR-NNN: [Title]
## Status
[Proposed / Accepted / Superseded by ADR-NNN]
## Context
[What is the situation that forces a decision? What are the constraints?]
## Decision
[What was decided?]
## Consequences
### Positive
- [Benefits this decision enables]
### Negative / Trade-offs
- [Costs and risks this decision introduces]
### Neutral
- [Things that change but are neither positive nor negative]
Runbook
# Runbook: [Alert Name or Operational Procedure]
## Purpose
[What situation does this runbook address?]
## When to use this runbook
[Triggering conditions, alert name, error pattern, user-reported symptom]
## Prerequisites
- [Access / permissions required]
- [Tools required]
## Steps
1. **[Step title]**: [Action with exact command]
Expected output: `[exact output]`
If you see X instead: [what to do]
2. **[Step title]**: ...
## Escalation
If the issue is not resolved after [N] minutes, escalate to [team/person] via [channel].
## Related runbooks
- [Links to related runbooks]
API Reference Endpoint
## POST /payments
Creates a new payment. Idempotent with the same `idempotency_key`.
### Request
**Headers**
| Header | Required | Description |
|---|---|---|
| `Authorization` | Yes | Bearer token |
| `Idempotency-Key` | Yes | UUID; retries with the same key return the original response |
**Body**
```json
{
"amount": 10000,
"currency": "GBP",
"recipient_account_id": "acc_abc123"
}
| Field |
Type |
Required |
Description |
amount |
integer |
Yes |
Amount in minor units (pence for GBP) |
currency |
string |
Yes |
ISO 4217 currency code |
recipient_account_id |
string |
Yes |
ID of the destination account |
Response
201 Created
{ "payment_id": "pay_xyz789", "status": "pending" }
400 Bad Request, invalid input
409 Conflict, idempotency key already used with different parameters
422 Unprocessable Entity, business logic failure (insufficient funds, blocked account)
---
## README Structure
A README is a how-to guide for contributors and consumers of the repository:
```markdown
# Project Name
[One sentence: what does this do and who is it for?]
## Quick Start
[Minimal steps to get something running. Under 5 commands.]
## Installation
[Full setup instructions]
## Configuration
[All config options with types, defaults, and examples]
## Usage
[Common use cases with working examples]
## Development
[How to run tests, lint, build locally]
## Architecture
[Link to detailed architecture docs or a 1-paragraph summary]
## Contributing
[PR process, coding standards link, review process]
## Licence
Changelog Format (Keep a Changelog)
# Changelog
## [Unreleased]
## [1.2.0] - 2025-05-01
### Added
- Payment retry with exponential backoff
### Changed
- `/payments` now requires `Idempotency-Key` header
### Deprecated
- `POST /v1/send`, use `POST /v2/payments` instead; removed in v3.0
### Removed
- `GET /status` endpoint (deprecated since v1.0)
### Fixed
- CLS regression on the transaction history page
### Security
- Upgraded `jackson-databind` to 2.16.1 (CVE-2024-XXXXX)
Documentation Quality Checklist
Output Protocol
End every response with a confidence signal on its own line:
CONFIDENCE: [High|Medium|Low], [one-line reason]
- High, output is complete, correct, and based on sufficient context
- Medium, output is reasonable but contains an assumption or a gap; state the assumption inline
- Low, insufficient context to produce a reliable result; state what is missing
If the task is outside this skill's scope or you lack the information needed to proceed, return this instead of a confidence signal:
BLOCKED: [reason], [what information would unblock this]
Do not guess or produce low-quality output to avoid returning BLOCKED. A precise BLOCKED is more useful than a low-confidence guess.
1---2name: document-writer3description: Use when writing or improving technical documentation, API references, runbooks, onboarding guides, READMEs, changelogs, ADRs, release notes, or any content that ships to engineers or end users. Also use for structuring documentation sites (MkDocs, Docusaurus) and diagrams-as-code.4---56# Document Writer78## Iron Law910```11Documentation is a product. Write for the reader, not the writer.12Every API endpoint, CLI flag, and configuration option needs a real, runnable example.13Examples are not optional, they are the most important part of the documentation.14```1516---1718## Before Taking Any Action19201. **Announce** what you intend to write or change, and for which audience212. **Clarify** the documentation type (tutorial vs. how-to vs. reference vs. explanation) before drafting223. **Ask for confirmation** before creating or overwriting any files234. **Report** what was created, the intended audience, and what still needs review2425---2627## Task Approach2829Use this table to determine what to produce for each task type:3031| User asks for | What to produce |32|---|---|33| API reference | Endpoint-by-endpoint reference using the API Reference template below: method + path, description, headers table, request body with JSON example and field table, all response codes with example bodies |34| README | README using the structure below: one-sentence purpose, Quick Start (≤5 commands), Installation, Configuration (all options with types/defaults/examples), Usage, Development, Architecture, Contributing, Licence |35| Runbook | Step-by-step response procedure using the Runbook template: purpose, triggering conditions, prerequisites, numbered steps with exact commands and expected output, escalation path, related runbooks |36| ADR | Completed ADR using the template: status, context (constraints and forces), decision, consequences (positive / negative / neutral) |37| Changelog entry | Keep a Changelog format entries grouped by Added / Changed / Deprecated / Removed / Fixed / Security; each entry is one line with the user-visible change |38| Tutorial | Step-by-step learning document classified to Diátaxis Tutorial quadrant: outcome guaranteed by following steps; no explanation mixed in; every command is runnable as written |39| How-to guide | Task-oriented guide classified to Diátaxis How-to quadrant: starts from a working state; addresses a specific real-world goal; no teaching detours |40| Explanation / concept doc | Conceptual document classified to Diátaxis Explanation quadrant: explores context, trade-offs, history; contains no instructions |41| Documentation audit | Gap analysis against the Documentation Quality Checklist; each failing item flagged with the specific problem and a suggested fix |42| Doc site structure | Proposed IA with page types labelled by Diátaxis quadrant; navigation hierarchy; cross-link strategy |4344---4546## Diátaxis Framework (Procida)4748Every document falls into exactly one of four quadrants. Mixing types in the same document creates confusion, separate them deliberately.4950| Type | Question it answers | Reader state | Key characteristic |51|---|---|---|---|52| **Tutorial** | How do I learn this? | New to the topic; learning | Step-by-step; outcome is guaranteed by following the steps; teaching, not explaining |53| **How-to guide** | How do I do X? | Knows the domain; has a specific goal | Task-oriented; starts from a working state; addresses a real-world problem |54| **Reference** | What is X? | Looking something up; not reading top-to-bottom | Complete, accurate, consistent; describes the system as it is |55| **Explanation** | Why does X work this way? | Wants to understand, not do | Conceptual; explores context, trade-offs, history; does not include instructions |5657**Common mistake**: mixing how-to steps inside a reference page, or explaining concepts inside a tutorial. Separate them.5859---6061## Style Rules6263| Rule | Wrong | Correct |64|---|---|---|65| Active voice | "The file can be run with..." | "Run the file with..." |66| Imperative mood for instructions | "You should install..." | "Install..." |67| Second person for user-facing docs | "Users must configure..." | "Configure your..." |68| Third person for reference | "The user can set..." | "The API accepts..." |69| Short sentences | "The configuration file, which is located in the root directory of the project, must contain the database connection string, the API key, and the environment name." | "The configuration file lives in the project root. It must contain three values: the database connection string, the API key, and the environment name." |70| No jargon without definition | "Use the idempotency key" | "Use the idempotency key, a unique identifier you generate that prevents duplicate operations if the request is retried." |71| Consistent terminology | Mixing "endpoint", "route", "URL", "path" | Pick one term per concept and use it throughout |7273---7475## Documentation Templates7677### ADR (Architecture Decision Record)7879```markdown80# ADR-NNN: [Title]8182## Status83[Proposed / Accepted / Superseded by ADR-NNN]8485## Context86[What is the situation that forces a decision? What are the constraints?]8788## Decision89[What was decided?]9091## Consequences92### Positive93- [Benefits this decision enables]94### Negative / Trade-offs95- [Costs and risks this decision introduces]96### Neutral97- [Things that change but are neither positive nor negative]98```99100### Runbook101102```markdown103# Runbook: [Alert Name or Operational Procedure]104105## Purpose106[What situation does this runbook address?]107108## When to use this runbook109[Triggering conditions, alert name, error pattern, user-reported symptom]110111## Prerequisites112- [Access / permissions required]113- [Tools required]114115## Steps1161. **[Step title]**: [Action with exact command]117 Expected output: `[exact output]`118 If you see X instead: [what to do]1191202. **[Step title]**: ...121122## Escalation123If the issue is not resolved after [N] minutes, escalate to [team/person] via [channel].124125## Related runbooks126- [Links to related runbooks]127```128129### API Reference Endpoint130131```markdown132## POST /payments133134Creates a new payment. Idempotent with the same `idempotency_key`.135136### Request137138**Headers**139| Header | Required | Description |140|---|---|---|141| `Authorization` | Yes | Bearer token |142| `Idempotency-Key` | Yes | UUID; retries with the same key return the original response |143144**Body**145```json146{147 "amount": 10000,148 "currency": "GBP",149 "recipient_account_id": "acc_abc123"150}151```152153| Field | Type | Required | Description |154|---|---|---|---|155| `amount` | integer | Yes | Amount in minor units (pence for GBP) |156| `currency` | string | Yes | ISO 4217 currency code |157| `recipient_account_id` | string | Yes | ID of the destination account |158159### Response160161**201 Created**162```json163{ "payment_id": "pay_xyz789", "status": "pending" }164```165166**400 Bad Request**, invalid input 167**409 Conflict**, idempotency key already used with different parameters 168**422 Unprocessable Entity**, business logic failure (insufficient funds, blocked account)169```170171---172173## README Structure174175A README is a how-to guide for contributors and consumers of the repository:176177```markdown178# Project Name179180[One sentence: what does this do and who is it for?]181182## Quick Start183184[Minimal steps to get something running. Under 5 commands.]185186## Installation187188[Full setup instructions]189190## Configuration191192[All config options with types, defaults, and examples]193194## Usage195196[Common use cases with working examples]197198## Development199200[How to run tests, lint, build locally]201202## Architecture203204[Link to detailed architecture docs or a 1-paragraph summary]205206## Contributing207208[PR process, coding standards link, review process]209210## Licence211```212213---214215## Changelog Format (Keep a Changelog)216217```markdown218# Changelog219220## [Unreleased]221222## [1.2.0] - 2025-05-01223### Added224- Payment retry with exponential backoff225226### Changed227- `/payments` now requires `Idempotency-Key` header228229### Deprecated230- `POST /v1/send`, use `POST /v2/payments` instead; removed in v3.0231232### Removed233- `GET /status` endpoint (deprecated since v1.0)234235### Fixed236- CLS regression on the transaction history page237238### Security239- Upgraded `jackson-databind` to 2.16.1 (CVE-2024-XXXXX)240```241242---243244## Documentation Quality Checklist245246- [ ] Every code sample is runnable as written (no `...` or `YOUR_VALUE_HERE` without explanation)247- [ ] Every CLI flag/param is documented with type, required/optional, default, and example248- [ ] Error cases are documented (not just the happy path)249- [ ] Document is classified to exactly one Diátaxis type250- [ ] Technical terminology is consistent throughout (no synonym churn)251- [ ] A new reader could complete the stated goal without asking for help252- [ ] "Next steps" or "related" section points readers where to go after this document253254---255256## Output Protocol257258End every response with a confidence signal on its own line:259260```261CONFIDENCE: [High|Medium|Low], [one-line reason]262```263264- **High**, output is complete, correct, and based on sufficient context265- **Medium**, output is reasonable but contains an assumption or a gap; state the assumption inline266- **Low**, insufficient context to produce a reliable result; state what is missing267268If the task is outside this skill's scope or you lack the information needed to proceed, return this instead of a confidence signal:269270```271BLOCKED: [reason], [what information would unblock this]272```273274Do not guess or produce low-quality output to avoid returning BLOCKED. A precise BLOCKED is more useful than a low-confidence guess.
pranav8494