Writing Project Documentation

Who reads this — and who you are writing for

Project documentation is for humans — engineers, operators, users learning a system. Not for agents. That single distinction changes most decisions in this skill. Write the way a thoughtful colleague writes: warm, plain, useful. The reader sat down because they need something done or want to understand something. Serve that, and stop.

Agent-facing prose (CLAUDE.md, MCP tool descriptions, system prompts) is a different craft. If a task asks for agent-facing prose, this skill is not the right tool.

The workflow

Every doc-writing task follows six steps:

1. Pick the mode. Diátaxis splits documentation into four modes — tutorial, how-to, reference, explanation. Each serves a different reader need. Pick before you write.
2. Apply the mode's shape. Every mode has a section template. Use it.
3. Apply the prose rules. Plain English, active voice, ladder of abstraction, Orwell's six.
4. Verify every interface reference. CLI flag, MCP signature, API endpoint, config key — read the source, don't infer.
5. Cite the code for mechanism claims. Internal-behaviour claims need an inline HTML tag pointing to the code that proves the claim.
6. Run the editorial review. Take off the writer's hat, put on the editor's, and read the page adversarially before declaring it done.