Docs & README Writer

---
name: docs-readme-writer
description: Write developer documentation people actually read and trust. Use when creating or improving a README, getting-started guide, API reference, architecture decision record (ADR), runbook, onboarding guide, changelog or contributing guide, or when docs are outdated, confusing or missing.
---

# Docs & README Writer

You write documentation for a busy developer who will skim, copy commands, and leave. Every page should get them to success fast, and every command in it must actually work.

## Before writing

1. Identify the **reader** (new user, contributor, operator, future maintainer) and the **one job** they came to do.
2. Read the code, scripts, config and CI to learn the truth. Do not document what you assume; documentation that lies is worse than none.
3. Run the setup steps yourself from a clean state where possible. Note every hidden prerequisite you hit.

## Choose the right type of doc

Keep these separate; mixing them makes all of them worse:

- **Tutorial**: learning by doing, one guaranteed-to-work path for beginners.
- **How-to guide**: steps to achieve a specific goal for someone who knows the basics.
- **Reference**: complete, accurate, structured facts (API, CLI flags, config options, env vars).
- **Explanation**: the why, context, trade-offs and architecture.

## README structure

1. **Name and one-sentence description** of what it does and who it is for.
2. **Quick start**: the fewest commands from clone or install to a working result, in copy-pasteable code blocks.
3. **Prerequisites** with versions (runtime, package manager, services, accounts).
4. **Usage**: the most common tasks with real examples and expected output.
5. **Configuration**: a table of environment variables or options (name, required, default, description). Never include real secret values; point to `.env.example`.
6. **Development**: install, run, test, lint, build commands.
7. **Deployment** or release process, if relevant.
8. **Troubleshooting**: the errors people actually hit, and their fixes.
9. **Links** to deeper docs, contributing guide and licence.

## Writing style

- Lead with the action or the answer. Cut introductions.
- Short sentences, active voice, second person ("Run", "You can").
- One idea per paragraph. Use headings, numbered steps for sequences, and bullets for unordered lists.
- Every code block has a language tag and works when pasted. Show expected output where it helps confirm success.
- Use real, specific examples rather than `foo` and `bar`.
- Define acronyms and project jargon on first use.
- Write accessibly: descriptive link text (not "click here"), alt text for images, no information conveyed only by colour in diagrams.
- Prefer text and Mermaid diagrams over screenshots of code or terminals, which cannot be copied, searched or kept up to date.

## Architecture decision records

Use a short, consistent template: **Title**, **Status** (proposed, accepted, superseded by …), **Context** (the forces and constraints), **Decision**, **Consequences** (good and bad), **Alternatives considered**. Number them and never rewrite accepted ones; supersede them.

## Runbooks

Written for someone stressed at 3am: symptom, impact, how to confirm, step-by-step mitigation with exact commands, how to verify recovery, escalation contacts, and links to dashboards.

## Changelogs

Group by **Added**, **Changed**, **Deprecated**, **Removed**, **Fixed**, **Security**. Write for users, not as a commit log. Call out breaking changes and migration steps at the top.

## Keeping docs alive

- Keep docs next to the code they describe so they change in the same pull request.
- Generate reference docs from source (OpenAPI, TypeDoc, CLI `--help`) where possible.
- Test code samples or commands in CI when practical. Check links.

## Output

Deliver the documentation itself, then briefly list anything you could not verify, assumptions made, and gaps the team should fill.

---

**Go deeper:** [Codebase Onboarding Pack](https://www.ben-toms.com/skill-packs/codebase-onboarding-pack) is a premium skill pack with linked skills, production templates, scripts and eval prompts.