Menu
Load before writing or updating any documentation. Required by the technical-author agent — covers the Diataxis document-type framework, writing principles, interface-element reference template, README structure, working examples, voice and tone, and coverage standards.
| name | technical-writing |
| description | Load before writing or updating any documentation. Required by the technical-author agent — covers the Diataxis document-type framework, writing principles, interface-element reference template, README structure, working examples, voice and tone, and coverage standards. |
| license | AGPL-3.0-or-later |
| allowed-tools | read |
Good documentation is a product, not an afterthought. It has an intended reader, a clear purpose, and a structure that serves that purpose. This skill covers how to plan, write, and maintain user-facing documentation for software projects.
Every piece of documentation belongs to exactly one of four types. Mixing types in a single document is the most common cause of documentation that is long but unhelpful.
| Type | Oriented towards | Answers | Analogy |
|---|---|---|---|
| Tutorial | Learning | "How do I get started?" | Lesson |
| How-to guide | Goals | "How do I do this specific thing?" | Recipe |
| Reference | Information | "What does this option/flag/type do?" | Map |
| Explanation | Understanding | "Why does it work this way?" | Essay |
Tutorials lead the reader through a complete, meaningful task with no assumed knowledge. Every step must work. The reader should finish with something running, not just read about something that could run.
How-to guides assume the reader knows the system and wants to accomplish a specific goal. They are shorter than tutorials, skip background, and go straight to the steps. Each guide solves exactly one problem.
Reference documents describe the system exhaustively and accurately. CLI flag reference, API docs, configuration schema — these are reference. They do not teach or explain; they record. Completeness and accuracy are the only metrics.
Explanation documents discuss why — design decisions, tradeoffs, background concepts. They do not instruct. They are for readers who want to understand, not just use.
Before writing any documentation, decide which type it is. If you cannot decide, split it.
A project is not adequately documented until a new user can answer all of these without asking anyone:
These are not optional. Missing any one of them is a documentation gap, not a style preference.
Regardless of project type — CLI subcommand, HTTP endpoint, UI screen, exported function, configuration option — every interface element must be documentable by answering the same five questions:
Apply this template to every interface element in the project. The form of each answer varies by project type; the questions do not.
Before writing a word, answer: who will read this? A new user who has never seen the tool? An experienced user looking up a flag? A developer adding a feature? Each audience needs different depth, vocabulary, and assumed knowledge. Write for one audience per document.
Write what the software does, not what happens to the user.
| Avoid | Prefer |
|---|---|
| "The config file will be read by myapp" | "myapp reads the config file" |
| "Errors should be reported to stderr" | "myapp writes errors to stderr" |
| "The flag can be set to override…" | "Set the flag to override…" |
Use the imperative mood for all instructional steps: "Run", "Set", "Open", "Create". Not "You should run" or "You will need to set".
Describe what the software does in the present tense: "myapp creates a record", not "myapp will create a record".
Lead with the essential. Detail comes after. Structure every document so a reader who stops after the first paragraph has still learned the most important thing. Bury prerequisites, advanced options, and edge cases towards the end.
Show, then tell — or show instead of telling. A working example communicates more precisely than a paragraph of description, and it is checkable.
These words add length without adding information. Remove them on sight:
If a paragraph contains two ideas, split it. A paragraph is not a list of loosely related sentences — it is a unit of thought. If you cannot summarise a paragraph in a single sentence, it needs to be split or restructured.
Technical documentation is not formal prose, but it is not casual chat either.
Reference documentation describes the system exhaustively and accurately. Every interface element — CLI subcommand, HTTP endpoint, UI screen, exported function, configuration key — follows the same underlying structure. Adapt the terminology to the project type; the structure stays the same.
For each interface element, document:
Do not omit sections because they seem obvious. "No parameters" and "always succeeds" are valid answers and should be stated.
Good examples:
<foo> unless the user must substitute something# Create a project using the default image
mytool create my-project
# Create using a specific registry image
mytool create --image registry.example.com/team/devenv:latest my-project
When documenting interfaces that can fail, describe the common failure modes and what to do. "If X fails with Y, check Z" is more useful than omitting error handling entirely.
A README is the front door. It must work for a reader who has never heard of the project and a reader who used it last month and needs a quick reminder.
Required sections, in order:
DEVELOPMENT.md.Optional but valuable:
Sections to avoid:
CHANGELOG.mdAn example that does not work is worse than no example. It wastes the reader's time and destroys trust.
Rules for examples:
my-project is better than <project-name>. Use values that look like what a user would actually type.The minimal working example (MWE) is the single most important piece of documentation after the project description. It must:
#, ##, ###) not Setext (===, ---)```bash, ```go, ```yaml[myapp documentation](url) not [click here](url)Use tables for comparative reference information (parameter descriptions, option comparisons, endpoint summaries). Do not use tables for sequential steps or narrative content.
Documentation that is not maintained becomes a liability. Every change to the interface, behaviour, or architecture of a project must trigger a documentation review.
Checklist for documentation changes accompanying a code change:
When to create new documentation vs. update existing:
Load before planning or routing any task. Required by mission-control — maps task archetypes to ordered sequences of specialist agents, with handoff context and success criteria for each step.
Load before reviewing any phase. Required by all internal reviewer agents — covers adversarial review philosophy, the approve/reject verdict contract, and escalation policy.
Load when operating as a sub-agent invoked via the agent tool — covers handoff mode detection, autonomous execution, clarification protocol, and the minimum completion report contract.
Load before running a comprehensive review. Covers scope resolution, pre-flight tool checks, parallel specialist dispatch, synthesis, and output format.
Recipe reference for installing tools in the container environment. Used by bootstrap and specialist reviewer agents to look up the correct install command for any tool.
Load before any API or CLI interface review. Required by the api-reviewer agent — covers REST naming, HTTP semantics, error consistency, breaking changes, CLI conventions, pagination, auth, and a three-tier severity model.
