Write change notes
When you update content on an already published page, you may need to write a change note.
You do not need to write a change note if you’ve only:
- fixed typos
- made style changes, like changing a heading or layout
- updated or removed broken links (unless they are links to something that is crucial to the task or knowledge that users need)
You should write a change note if you’ve:
- added new information that means a user has to do something differently or know something new
- removed guidance that is out of date or misleading
- updated changes to fees or deadlines
Know who can see change notes
Change notes are public. They are:
- emailed to anyone who subscribed to the page
- emailed to anyone who subscribed to the topic or organisation that the page is tagged to
- sometimes published on the page, along with the time and date of the change
This means change notes need to be:
- very clear about what has changed and where the change appears on the page
- used carefully so users are not being sent emails about changes that are irrelevant to them
You can sign up to an email alert to get an idea of what they look like when a user gets them.
Write clear change notes
Before you write a change note make sure that you:
- understand what has changed and how this is important for the user
- get any policy or communications input needed to make sure you’re able to clearly explain what has changed and any potential impact for the user
Include the changed information in the change note itself if possible, so users can see what has changed without having to go to the page itself.
If a lot of content is being changed at once, write a summary of:
- what has changed
- where it’s been changed, such as the page number, chapter or section
Change notes should:
- be as specific as possible
- be written in full sentences
- include the most important information about what has changed first
Do not say the page has been updated without saying what has changed.
Some examples of good change notes include:
- “Potatoes are now on the banned vegetable import list from outside the EU.”
- “Edited chapter 6 - centres in Cardiff and Aberystwyth have closed. There’s only one service centre now, in Merthyr Tydfil.”
- “Form A123 - question 4 on page 2 now asks for your previous address.”
- “New guidance on school meal procedures that apply from 1 March 2019 added to the ‘Meal planning for primary schools’ section.”
Some examples of bad change notes are:
- “Guidance updated.”
- “Updated the collection page to inform users of the name of the publication.”
- “Updated to add social media graphics for Twitter and Facebook.”
- “Removed broken link.”