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

Copy docs.md

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.