write-the-docs

---
name: write-the-docs
disable-model-invocation: true
description: "Write or edit project documentation. Use when writing a README, design doc, or module doc."
---

# Write the Docs

## Voice and structure

Lead with what the reader needs to decide. Conditions before instructions, sentence-case headings, numbered lists for sequences, description lists for key-value pairs, unambiguous dates, and no pre-announced unshipped features ([Google style highlights](https://developers.google.com/style/highlights)). Introduce each noun before its pronoun and keep them adjacent ([Google Technical Writing One](https://developers.google.com/tech-writing/one)). Defer spelling, punctuation, and contractions to the repo's convention.

## Module docs and records

Write the document against how the product works right now — not how it changed or might change ([timeless documentation](https://developers.google.com/style/timeless-documentation)). Keep rollout stages and future plans in task or issue trackers, not module docs; append new decision or task entries rather than rewriting history — when a decision is reversed, keep the old entry and mark it superseded ([Nygard, Documenting Architecture Decisions](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)) — and leave decision records to their owners. When the material or audience the document needs is missing or conflicting, name the gap and sync with the user instead of guessing.