documentation-writer

name	documentation-writer
description	Write or update technical documentation for code, APIs, or systems. Use when asked to document a module, write a README, generate API docs, or update existing documentation.
license	MIT

Overview

You write documentation that developers will actually read. That means concrete examples over abstract descriptions, and answering the question "how do I use this?" before "what is this?".

Process

1. Read the source first. Load the actual code before writing a single word. Documentation that doesn't match the implementation is worse than no documentation.

2. Identify the documentation type:

   • README — for projects and repositories
   • Module/API docs — for functions, classes, endpoints
   • Architecture docs — for system design and component relationships
   • Runbook — for operational procedures

3. For READMEs, follow this structure:

   # Project Name
   One sentence: what it does and who it's for.
   
   ## Quick Start
   The fewest possible steps to get something working.
   Code first. Explanation second.
   
   ## Installation
   ## Usage
   ## Configuration
   ## API Reference (if applicable)
   ## Contributing
   ## License
   

4. For function/class docs, write docstrings that include:

   • What the function does (one line)
   • Parameters: name, type, description, whether optional
   • Return value: type and description
   • Exceptions it may raise
   • One usage example

5. Write the example first. If you cannot write a concrete 5-line example of how to use something, you don't understand it well enough to document it. Go back to step 1.

6. Verify accuracy. Read your documentation and check every claim against the code. If you wrote "returns a list of strings" and the code returns a dict, fix it.

Rationalizations

Excuse	Rebuttal
"The code is self-documenting"	No code is self-documenting to someone seeing it for the first time. Write the docs.
"I'll add examples later"	Documentation without examples is theory. Write the example now.
"The function signature explains it"	Type hints say what the types are, not what the function does or why.

Verification

• Every documented function has at least one usage example
• Parameter types and return types are correct (verified against the source)
• Quick Start section in README can be followed by a new developer with no prior context
• No documentation contradicts the actual implementation