Over the years, from time to time, I have received criticism over the release notes I have written. That’s fair, I certainly have written some crappy release notes on occasion. However sometimes I get the feeling that those criticizing believe that somehow all developers, no matter how junior, should be genetically implanted at birth with the knowledge of how to always write good release notes. Being able to write good release notes, code, or any other form of writing is a skill that takes hard work to learn and develop. Writing good release notes is hard. In this post I’ll cover some of the reasons why it is so hard and some tips to do better.
Release notes should sell the product being released. There should be a definite marketing aspect to release notes. The release notes should make the customer want to buy the product or install the upgrade. This can make some developers uncomfortable. Their job is to write code, not market the product. To force them into this role can make them feel a bit like a whore.
Although marketing can feel uncomfortable at first, it is something that everyone should get familiar with. Everyone, no matter what profession, should be able to explain the value that they are providing to both their customers and employers. Being able to describe this completes a feedback loop that ensures that everyone (the employee, the employer, and the customer) are all aware of the value of the services being provided. Not being able to describe this is a red flag that you may be delivering the wrong thing for the customer. As I’ve said before, if you aren’t sure of the value of a work item stop and figure that out before continuing.
Release notes should be very short and to the point. They don’t even need to be full sentences. They should read more like newspaper headlines. Be sure to provide links to bug/enhancement system tracking records, user manuals, or feature release blog posts so that anybody can dive deeper if they need to.
Ideally, there should be symmetry between each point in the release notes. You don’t want to list “fixed a spelling error” and “new feature that cures cancer” as if they are the same level of importance. Minor issues can be grouped together. The individual issues can be made available from an external link, collapsible region, or indented sub-bullets. When symmetry is not possible, lead with the larger issues.
When writing release notes, or any form of writing, it is important to know the audience. Not all issues are going to be important to all users. Group issues into sections or separate documents for different readers. There are a number of ways to group issues.
Items can be grouped into bug fixes or enhancements. New users aren’t concerned with bug fixes, but users that routinely submit bug reports will be interested in the new fixes.
Sometimes separate public and private release note documents can be beneficial. Private release notes can go into more details of the technical debt that was cleaned up, which could be plain boring to external customers. Although there can be benefits to the approach, beware that is can lead to a lack of transparency with the customers.
Really when it comes down to it, grouping issues by audience really comes to down to identifying different roles or personas within your user base. New or existing users, external or internal customers are just some roles. Others can include: casual users, power users, system administrators, IT or operations.
Like other writing, release notes will benefit from an editor or peer review process. Various people should have input on release notes. These are: the programmer, the product manager, marketing, and a technical writer. It doesn’t matter which of these people is the original author of the release notes, as long as the each of these people have their area of expertise represented in the final version.
The programmer that did the actual work must review the release notes. Only they are aware of the work that was truly done. For this reason they are typically the original author of the release notes. If they are the original author it is import that they review the final release note too. Primarily this is ensure there is a feed back loop. When they see how others have edited their release note, this will make them do a better job the next time.
The second reason the programmer needs to review the final release note is to check for accuracy. Sometimes a programmer’s initial release note may read something like “I have no idea what’s going on with this bug. I cleaned some stuff up and hopefully this might reduce the error rate”. But by the time marketing gets done the release notes turns into “all bugs fixed”. The original author needs to make sure that the multiple people’s cumulative edits have not corrupted the original message.
The product manager needs to make sure that the release notes tell a story that is consistent with the overall vision for the product. They also need to make sure the release note aligns with the original user story that triggered it.
Marketing can verify the release notes carries a message that is consistent with helping new sales and upgrades to existing customers. The release note needs to be consistent with the overall product vision and the marketing message around it.
A technical writer can check the release notes for formatting, consistency, and all the little important details that may be overlooked by others.
Leverage automated tools for building release notes, but be wary of automatically generated documents. It is invaluable to have access to a bug/enhancement tracking system when doing release notes to verify the issues that are included in each build. A good system will also let you enter a release note for each issue and those will be compiled into an automatically generated release notes document.
Some systems allow various options for how the release notes document is formatted. One of the biggest factors in this is whether the document is generated for a single build, provides a running list over multiple builds with different sections for each build, or is a single flat list of all issues over multiple builds. These options can have serious impact on the document produced.
When the tool automatically merges multiple builds together it is nearly impossible to have the tool do a good job on symmetry of items. Although some groupings yield good release notes when looking at a single build, over multiple builds the groupings may need to be revisited. The telling of a consistent story also quickly breaks down.
Imagine if you had to write an email consisting of about a dozen sentences. Image that you were only allowed to write one sentence per day. The order that you write the sentences is not the order you want the sentences to be arranged in the final email. The tooling may not make it easy to review the sentences from previous days when writing the new one. Also, other people will be contributing their own sentences to be included in the email. This is what it is like to enter in release notes as a field in a bug tracking system and have and automated release notes report attempt to produce a comprehensible document.
For these reasons, an automated release note document should only be used to automate some of the work in providing the final release notes document. The output of the automated tool must be reviewed and edited so that all issues are cleaned up.
Hopefully this helps. Happy release noting.