如何撰寫用戶真正會看的版本更新説明
How to Write Release Notes People Actually Read
版本更新説明應按用戶在應用程式中的操作流程分組,並以用戶獲得的結果開頭。應省略用戶看不到的內部修正、測試資料和開發工具,文字保持簡短、平實。文中介紹的免費 AI 工具套件可根據 review notes 和 pull requests 草擬版本更新説明,按用戶任務分組並放在發佈內容頂部。
People read release notes that tell them what got better for them. Group the notes by what people do in your app, lead every line with what they get, and leave out anything they never saw. Your AI can draft all of it from your pull requests. The free AI starter kit we build our own products with writes notes this way on every release.
Group by what people do
Follow the path a person takes through your product, in the order they take it. Write each heading as "When you ...":
- When you first open the app
- When you do the main task, with a heading for each main task
- When you organize or find your work
- When you change what the app uses, like sources, plans or connections
- Settings
- The look everywhere, for changes that touch every screen
Skip any heading with nothing new under it.
Lead every line with what the user gets
Under each heading, write one bold line with the outcome, then a few bullets with the specifics. Write "The model list opens straight away", never "Virtualized the remote model list". Use a real number only when it's true and checked, like "about half a second, down from nearly three".
Leave out what nobody saw
Cut bugs you made and fixed inside the same release, test data, developer tools and internal checks. If a user would never notice it, it doesn't belong in the notes.
Keep it short
One line under the title, then the headings. Speak to "you", in short sentences and everyday words. No component names, no code names, no closing summary.
Before and after
| Before | After |
|---|---|
| Refactored the auth flow | You stay signed in after an update |
| Fixed race condition in sync | Notes you write offline show up on your phone |
| Updated dependencies | Leave it out unless users notice a change |
| Misc bug fixes | List the fixes people would notice, or leave the line out |
Get the release notes tool we use
The starter kit turns your review notes and pull requests into release notes grouped by what people do, in your product's voice, and puts them at the top of the release. Get the starter kit free on GitHub.
Questions
How should release notes be organized?
By what people do in your app, in the order they do it, like when you first open the app, when you do the main task, and settings. Skip any heading with nothing new.
What should each release note line say?
What the user gets, in plain words. Write "The model list opens straight away", never the technical change behind it.
Can AI write release notes from pull requests?
Yes. Give it the pull request comments and commit messages, tell it to group changes by user task and lead with outcomes, and have it drop anything users never saw.
Originally published at wednesday.is.
來源:DEV Community · dev.to