Write a Changelog People Actually Read
Added 2026-10-30
Organise by what users can notice, not by commit log order.
I am shipping a product update. I will give a list of changes (possibly technical). Write three sections users can follow: 1) the two or three changes users will noticeably feel, one sentence each; 2) fixes written as "before… now…"; 3) details for developers (collapsed). For each item decide whether a user can perceive it; if not, it goes in section three. No empty phrases like "improved experience".
Site original
Chinese original
How to use
更新日志写给用户看，不是写给提交记录看。
Try tweaking it
- Ask for three openings in different tones, then pick one.
- Replace "make it better" with concrete limits: length, reader, facts to keep.
What you should get
- A publishable draft, not an outline
- A short changelog: what changed and why
Common mistakes
- Letting it guess the facts, so plausible-looking sources get invented.
- Dumping the whole text with just "polish it" — the result still has no point.
How to check the output
- The conclusion comes first; deleting the opening paragraph does not break it.
- Every fact, number and quote traces back to the source text.
Where it works
- Good for: turning a rambling draft into a conclusion-first, shorter version.
- Watch out: keep sources and figures verbatim — do not let it invent citations.