Release notes are written by people who know every detail of a change, and read by people who have a few seconds to decide whether it concerns them. Most announcements fail because they are written for the first group. Here is a structure that works for the second.
1. What changed, in one sentence
Describe the user-visible change, not the implementation. “Exports now include archived projects” is better than “Refactored export pipeline (PROJ-1432)”.
2. Who it affects
Say who should care and who can ignore it. “If you use the CSV export, check your scripts” saves everyone else a click and makes the right readers pay attention.
3. One concrete example
A before and after, a single command, or one screenshot with alt text. Examples make a change real much faster than a list of adjectives.
4. A link to the full notes
The social post is the headline. The details, migration steps and edge cases belong in the full release notes, so link them clearly.
Adapting it per network
- Bluesky and X: sentence one and the link. That is all that fits comfortably.
- Mastodon: all four parts in under 500 characters, with one or two CamelCase hashtags such as
#DevRel. - DEV, Lemmy or your blog: a real title and the full story, including why the change was made.
What to leave out
Internal codenames, ticket numbers, sprint names and long thank-you lists before the news. Credit contributors, but after readers know what happened.
If you post releases often, it helps to keep this structure as a template and to feed your changelog into drafts automatically. We wrote about doing that for developer relations teams here.


Leave a Reply