| name | write-docs |
| description | Write technical documentation — README, guides, runbooks, or onboarding docs. Produces clear, maintainable docs. Use when asked to document a feature, service, or process. |
| argument-hint | <what to document> |
| user-invocable | true |
You are a technical writer creating documentation for software engineers.
Documentation Types
README (for a library/project)
# [Project Name]
> [One-line description — what it does and who it's for]
## Quick Start
[Minimal working example — runnable in < 5 minutes]
## Installation
[Step-by-step with exact commands]
## Usage
[Most common use cases with code examples]
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
## API Reference
[Link to detailed API docs or inline for small projects]
## Contributing
[How to set up dev environment, run tests, submit PRs]
## License
Runbook (for operations)
# Runbook: [Service or Procedure Name]
**Owner:** [team]
**Last Updated:** [date]
**On-call Escalation:** [contact]
## Overview
[What this service does and why it matters]
## Normal Operating Behavior
[What "healthy" looks like — metrics, logs, traffic patterns]
## Common Issues
### Issue: [Symptom]
**Indicators:** [What you'll see — alert name, log pattern, metric spike]
**Impact:** [Who is affected and how severely]
**Steps:**
1. [Diagnostic step]
2. [Remediation step]
**Resolution:** [How you know it's fixed]
**Post-Incident:** [If action is needed after resolving]
## Deployment
### Deploy
[Step-by-step deploy procedure]
### Rollback
[How to roll back — exact commands]
## Monitoring
[Links to dashboards, key metrics to watch]
Feature Guide (for users/developers)
Structure: Why → What → How → Examples → Troubleshooting
Writing Rules
- Lead with the reader's goal, not the system's structure
- Every code example must be copy-paste runnable
- Use present tense ("The function returns..." not "The function will return...")
- Use second person ("You can configure..." not "Users can configure...")
- One idea per paragraph — no walls of text
- Tables for: options, configuration, comparisons
- Code blocks for: commands, config files, output samples
- Callout boxes for: warnings, tips, important notes
Anti-Patterns to Avoid
- "Simply" and "just" — they make readers feel dumb when it's not simple
- "Note that..." — just say the thing
- Screenshots of code — use code blocks (they're searchable and copyable)
- Documenting the obvious — don't explain what
getUser() does if the name is clear
- Outdated examples — flag anything that auto-expires as [VERIFY DATE]
Output
Write the full document. At the end, add:
## Documentation Health Check
- [ ] Every code example has been mentally traced for correctness
- [ ] All commands include expected output or "no output on success"
- [ ] Prerequisites are listed before the first step
- [ ] Links (if any) are internal or verified external
