# Changelog tone guide

Release notes that customers actually read. The voice of the brand,
in 1 page.

---

## Voice — what we sound like

- **Concrete over abstract.** "Search now matches partial words" >
  "Improved search relevance."
- **Owner over team.** "I shipped" or "we shipped" beats "the team
  shipped." Names build trust.
- **Honest about tradeoffs.** "We picked speed over perfect ranking"
  beats "now even better."
- **Short.** A great changelog entry is 2 sentences and a screenshot.
  Reserve essays for blog posts.

## Format

```
### Title (verb-led)

One sentence: what changed and who it helps.

(Optional) One sentence: how to use it.

(Optional) One image / GIF.

(Optional) Link to docs / discussion.
```

### Examples

**Good**

> ### Filter feedback by source
>
> You can now filter the inbox by where feedback came from — widget,
> email, public board, or API. Useful when triaging post-launch.

**Bad**

> ### Source filtering improvements
>
> We've enhanced our filtering capabilities to provide users with
> additional ways to slice their feedback data, improving overall
> productivity and workflow optimisation.

(The bad one is 4× longer and says nothing.)

## Categories

Keep to 4. More and people stop scanning.

| Tag | Use for |
|-----|---------|
| Feature | New capability that wasn't there before |
| Fix | Bug fix or behaviour correction |
| Improvement | Better/faster/clearer existing thing |
| Breaking | API or behaviour change that may break customers |

## Cadence

- **Weekly is plenty.** Daily creates noise.
- **Skip empty weeks.** Don't manufacture entries.
- **Bundle small fixes.** "Improvements" tag → one entry per week
  with 3-5 bullets.

## Don't

- Don't write "we" for cosmetic changes you didn't make.
- Don't promise dates ("coming next week").
- Don't leak internal codenames.
- Don't auto-publish AI drafts without a human read.

---

*Print, tape next to your monitor, repeat.*