Every internal tool changes. A field is renamed, a button moves, an approval step is added, a report starts to include something it did not before. The people who use the tool usually find out in one of two ways: by hitting the change in the middle of their work, or by hearing about it from a colleague. Both feel like the tool is something that happens to them.
This article is for a technology lead or tool owner who wants a simple, repeatable way to tell staff what is new. It is about announcing changes, not about deciding which ones to accept; for that side, see handling change requests after launch.
Who actually reads release notes
Developers write release notes for developers: a list of fixes, version numbers, references to tickets. Staff are a different audience, and they read for different reasons.
- The daily user wants to know whether anything changes in what they do on Monday morning.
- The line manager wants to know whether to warn the team, and whether any process or training needs updating.
- The person who supports the tool wants to know what questions to expect.
- The new colleague, months later, wants to understand why the tool behaves the way it does.
If a note works for the first reader, it usually works for the others. So write for the daily user and keep every other need as a short extra line.
A five-line template
Use the same five lines every time. Staff learn where to look, and you do not need to invent a structure under time pressure.
- What changed. One sentence, in the words people use at work. "Orders now show the delivery date next to the customer name", not "Added delivery_date to order list view".
- Who it affects. Name the team or the task. "Everyone who enters orders", "Only the warehouse".
- What you need to do. Either a concrete action or "Nothing, it works as before". Put this line high if action is needed.
- What stays the same. Only if people might worry. If an approval step changed, say that the approval rights did not.
- Who to ask. A name or a channel, and the date until which you expect questions.
An example:
Order list: delivery date added. From Tuesday, the order list shows the delivery date next to the customer name. This affects everyone who enters or checks orders. You do not need to do anything. Sorting and filters work as before. Questions to Petra in the operations channel by Friday.
That is six sentences, and a reader can finish it in twenty seconds.
When to send them
Match the timing to the effect of the change.
- Changes that alter how people work - a new required field, a removed screen, a different approval path. Send the note before the change, with enough time for the line managers to react. A few working days is usually enough for a small tool. Send a short reminder on the day.
- Visible but harmless changes - a new column, a clearer label, a faster page. Send the note on the day or just after.
- Fixes that nobody noticed - collect them and mention them once in a regular summary, or leave them out. Staff do not need an apology for something that never reached them.
Choose a fixed place and rhythm. For a small tool, one place is enough: the same chat channel, a pinned message in the team space, or an email to a short list. A weekly or fortnightly summary, plus an extra note when something needs action, works better than many scattered messages.
What to leave out
Most release notes get worse by adding things. Leave out:
- Technical detail. Database changes, library updates and refactoring belong in the technical log.
- Ticket numbers and internal names. They help you, not the reader. Keep them in your own record.
- Long lists of minor fixes. Group them in one line: "Several small display fixes".
- Promises about the next version. If a date slips, the note becomes a source of distrust.
- Blame and excuses. Say what is different now and what to do.
When a change goes wrong, the rule is the same: say what happened, what is affected, what to do and when you will update. Do not wait for a full explanation if people are working around a problem.
Keep a short archive
Keep the notes in one place, newest first, with the date. This takes almost no effort and helps in three situations: someone asks "when did this change", a new colleague wants to see how the tool grew, and you need to hand the tool to someone else. It also fits naturally beside the two pages of documentation that a tool should have.
If you have just launched the tool, the early weeks are when people need these notes most; see the first 30 days after launching a new internal tool.
Common mistakes
- Writing from the developer's point of view. The note describes what was built, not what the reader will see.
- Hiding the action. The one thing people must do is in the fifth paragraph.
- Sending too often. If every notification is minor, people stop reading, and then miss the one that matters.
- Sending nothing for small changes. Many small unannounced changes add up to the feeling that the tool is unpredictable.
- No named contact. Questions go to whoever people happen to know, and the same question arrives five times.
- Announcing in a place nobody looks. Use the place staff already read daily. For wider changes in how people work, change management for technology adoption covers the longer view.
Checklist
- Write for the daily user, not for developers
- Use the same five lines: what changed, who, what to do, what stays, who to ask
- Put required action first
- Send before changes that alter work, after harmless ones
- Fix one place and one rhythm
- Leave out technical detail, ticket numbers and excuses
- Name a contact and a date for questions
- Keep a dated archive, newest first
Sources
- Our related articles linked above.
- The template and timing rules are a working practice, not a standard; adapt them to the size of your tool and your team. No client results or market figures are claimed in this article.
