Home › Agent workflows › Documentation writing rules

Documentation writing rules

Windsurf rules for writing and updating READMEs, docstrings, ADRs, and changelogs alongside code changes.

WindsurfAgent workflows

How to use

Save this as .windsurf/rules/docs.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# Documentation rules

## When to update docs
- Any change to setup, env vars, commands, public APIs, or config also updates the README or `docs/` in the same change.
- New env var: add it to `.env.example` and the configuration table.
- Notable user-facing changes get a line in `CHANGELOG.md` under `## [Unreleased]` (Keep a Changelog format).

## README structure
What it is (one paragraph) -> Quick start (copy-paste commands that work on a fresh clone) -> Configuration -> Common tasks -> Troubleshooting -> Contributing.

## Writing style
- Short sentences, active voice, second person ("Run `make dev`").
- Every command in a code block, exactly as typed, with the expected result when it isn't obvious.
- Explain *why* for non-obvious decisions; skip what the code already says.
- Use real examples, not `foo`/`bar`, when it helps understanding.
- Link instead of duplicating content across files.

## Code comments and docstrings
- Public functions and modules get docstrings (JSDoc/TSDoc, Google-style Python, rustdoc) describing purpose, params, return, and errors.
- Comments explain intent or constraints, never restate the line below.
- Remove stale comments when changing code.

## Decisions
Significant architectural choices get an ADR in `docs/adr/NNNN-title.md`: context, decision, consequences.

## Check
Run any doc commands you wrote to confirm they work, and check links.