When you realise the testers have signed off your latest release candidate and it is good to go, then the dread comes for the next necessary but hated task…. documentation.

As I got fed up with filling in and writing release notes for my teams over the years, we tried a few experiments at being lazy (i.e. intelligent task automation and not repeating work). A bit of upfront work to automate tasks is preferable to regular anguish and customers prefer it if the result is consistent and regular information.

The release note murky gap

Photo by mahdis mousavi on Unsplash
Why is it release notes fall into this murky gap between development and marketing teams? Who should write them? the developer? the product owner? the technical author? The arguments come thick and fast:

• product owner — as they understand the features and issues.
• developers — as they wrote the software so know it inside out.
• team leader/scrum master — as the software guys are too techie and no-one understands them but it needs someone close to it.
• testers — as they have a better understanding of how the features work in their entirety or how to reproduce the bugs the customer reported.
• marketing — as it is another opportunity to promote the product and message the customers.
• technical author — as it needs someone with some writing skills to decode the techie speak and explain it in plain english.

Timing of release notes

Photo by Nick Hillier on Unsplash

And the timing of creating and issuing release notes just as crucial:

• do it (create and update) as each ticket (feature or bug) is fixed.
• wait until end of the sprint and it has been neatly shown in a sprint review or demonstration.
• wait until the release candidate has passed and is locked and loaded for deployment.
• put it off and hope users don’t ask tricky questions.
• do it a week after deployment and only document what the users complain about/ask about the most.

Level of detail

Photo by Michael Longmire on Unsplash

The next question is how much detail to put in a release note?:

• top-level couple of sentences just explaining the goal and aim of the release e.g. security improvement
• mid-level detail explaining the approximate areas or changes e.g. login page security improved and password strengthened
• low-level detail explaining the exact area and change e.g. password strengthened by increasing minimum length from 8 characters to 12
• low-level with justification explaining exact area and change and reason e.g. password strengthened by increasing minimum length from 8 characters to 12 to meet security guidance note ABC123 for UK government
• low-level with justification and with traceability explaining exact area or change, reason and a reference identifier to trace it to any bug or change ticket e.g. BUG#123401 password strengthened by increasing minimum length from 8 characters to 12 to meet security guidance note ABC123 for UK government

An example of self-documenting software with in-built release notes

What was developed:

• automated build pipeline that updated notes on every build
• custom built tool to scan change lists in a release from the configuration management system and generate a list of tickets (bugs/changes) in a build.
• list of tickets and build number formatted and appended to an HTML page.
• HTML release notes page accessible within the web application from a Help > About page.
• HTML release notes page includes: ticket number, 1 line summary of ticket, hyperlinked to the ticketing system to show full ticket.
• HTML release notes page includes clear marker when an official external software release and its associated version number and date.

How was it used:

• Testers received a new build for checking, logged into the web application and accessed the release note page. Clicked on each item to access its relevant testing, and added test notes to the ticket.
• External users could access the release notes easily, however, hyperlinks to detailed tickets were disabled for them.

Learnings

The following items have been learnt the hard way or discovered over a period of time by the author and need careful consideration:

An automated system to generate release notes has many benefits and the payback time is very short.

• Some changes in a build are hidden through feature flags (dark releases) and may need to be hidden in a release note for certain users to avoid confusion.
• Original ticket titles written by end-users that are included in release notes are not clear and often refer to the wrong thing.
• Ticket titles need to be consistent through use of naming when referring to the product, modules, task and if they describe the symptom, problem or solution.
• Software developers don’t write clear release notes for end users.
• Someone in the team needs to be responsible for consistency, cleansing and reviewing of change ticket titles.
• Any step that requires manual intervention will be late or go wrong at some point.
• As teams become more efficient and deploy faster than release notes become more critical.
• Release notes need to be easily accessible and in a suitable format.
• Release notes that are vague or missing information are not trusted and have no value, so you may as well not produce them.

Tips

• Generation of release notes should be fully automated for every build.
• Release notes need to be timely and generated at the time of the build or release.
• There should be clarity in the release notes on naming and dates for external releases and internal builds.
• Having easy access to release notes at the point of use i.e. within the application is beneficial for users.
• Having easy access to release notes prior to the installation of any software update is beneficial for IT staff.
• Release notes should include details of all changes including references, dates, areas of change, type of change (defect or feature request or modification).
• Certain confidential changes may need to be filtered out based on the role of the reader or omitted entirely when generating the details.
• Release notes need to explain where a change has been made in a simple fashion (to allow readers to decide if the change impacts them and if they need to dig deeper or not).
• Release notes should hyperlink to more detailed information based upon the role of the user.
• Any hyperlinks to tickets should go through a middle layer/proxy to handle any future changes to the ticketing system.
• Release notes need to be augmented by user manuals/online guides/feature explanations.

More About The Author

Greg is an experienced software professional and CTO at outsource.dev , having worked in several businesses he is now passionate about helping others succeed in software development, management, and outsourcing.

If you enjoyed this article then please like it and follow me.