Blog
A Great Way to Write Release Notes
The Trouble With Release Notes
This week I have been shepherding our latest release into the production environment and I got stuck with the task of doing the release notes as well. The trouble with release notes is that they are boring and unloved.
The Problem
Release notes tend to be just lists of changes which hardly makes for inspiring reading. If you’re bored when writing them then why would you expect anyone reading them to continue to plough through the dross. You won’t necessarily have a large audience and you don’t need to write the next best seller but you can make them more engaging and easier to digest for those that do read them.
What Makes for Good Release Notes?
Wikipedia defines release notes as “…documents that are shared with end users, customers and clients of an organization…[that] detail the corrections, changes or enhancements made to the service or product the company provides”. This means that you have an audience of internal and external users that want to know what has changed in your product since the last release and so you should help them do this as quickly and pain free as possible.
In order to digest release notes it makes sense to order them into sections which means you have to do the work of sifting through the changes to categorise them for your readers. I finally settled on a template with help from this post.
Release Notes Template
- Release Title and DateThis should contain the name of the product, the version and the date of release.
- SummaryThis should be a headline description of what’s in the release. A few sentences should do.
- NewList any new features and functionality here. This might be at the user story level and could include links to the work item.
- ImprovementsOutline what changes and enhancements you have made to existing features. Again, include a link to the work item if you can.
- FixesPut your bug fixes so that your users know that you are removing errors from the system.
- Operational ChangesThese are under the hood changes that are not necessarily important to the users of the system but should be tracked. Include items here such as infrastructure changes or changes to deployment.
Example
Summary
This release introduces the ability to delete bits and bobs from the settings screen and enhances the reporting screen by adding a back button. The save to disk bugs have been fixed and the server hostnames have been tokenised as part of the deployment process.
New
Item 48923 Delete bits from settings screen
Item 48924 Delete bobs from settings screen
Improvements
Item 51344 Provide a way back from reporting screen
Item 48555 Restyle reporting tables to fit on mobile devices
Fixes
Item 48871 Error when save to file when filename longer than 12 chars
Item 48872 Error when save to file when filename has underscores
Operational
Item 48801 Tokenise server hostnames during deployment
Add Humour
I’ve also had some success with a slightly more humorous version, but you might have to think carefully about your audience.
The One Where (Summary)
…
Awesomeness (New)
…
Twerks (Improvements)
…
How Did We Miss These (Bug Fixes)
…
You Don’t Need To Know (Operational)
…
Love Your Release Notes
Ultimately, making your release notes clear and unambiguous shows that you are committed to engaging with your end users and can only help with the success of your product. Do your readers a favour and love your release notes.
Why Do We Always Forget About the Documentation?
The Agile Manifesto
The Manifesto for Agile Software Development states “Working software over comprehensive documentation” and for a long time many teams and individuals have taken this to mean that we don’t need to document our software.
Writing documentation can be hard. Not everyone is a fantastic wordsmith, especially in the development community where, mostly, we just want to build stuff. However, the same manifesto also states “Individuals and interactions over processes and tools”. What better way to enable individuals than to have decent documentation. Documentation that points you in the right direction, that explains things in ways that the code never can. Documentation that records design decisions so that those same interactions flow well.
Use a Software Travel Guide
Simon Brown, in his book “Visualising Software Architecture“, and Patrick Kua in his talk “Travel Guide to Software Systems” both advocate a “travel guide” style set of documentation. They argue that context setting is a necessary component of software development in much the same way that you would use a travel guide and map as a way to orient yourself in a city or country that you are unfamiliar with.
The travel guide concept is useful because it suggests a lightweight approach; something to get you started on your journey. An entry point into the tangled mess of an unknown software application. It can outline areas to watch out for. It can serve as a reminder for those who have travelled there before, including ourselves since we can often forget where we’ve been in this modern world of multi-tasking on projects.
What to include
What are the best things to document? Simon Brown suggests at a minimum you should include the following:
- ContextThis should outline what the software project is about. Who the main users and stakeholders are.
Include some kind of context diagram. - Functional OverviewThis expands on the context to outline the use cases of the system. What are its main features. What is the business workflow the system replicates. Some facts about the domain and glossary of terms.
- Quality AttributesThese are the non-functional requirements of the system such as scalability, performance and security.
- ConstraintsThis might include standards or protocols the system follows or constraints of the technology being used.
- PrinciplesThis can be about the culture around the development. Some examples here include coding standards or styles, logging, always use dependency injection, use Swagger rather than RAML, prefer thin client,
position of brackets, naming of tests. - Software ArchitectureHere you might find architecture diagrams (component/sequence/flow diagrams).
Discussion of the key architecture patterns, perhaps layering strategy. What are the deployable units. - Infrastructure ArchitectureWhere the software is deployed. Describe the physical hardware, database servers, message buses. Who maintains it. Backup and Disaster Recovery strategy.
- DeploymentHow the software is deployed to the infrastructure. Automated/Manual processes. Configuration settings. Deployment rollback strategy. Data replication.
- Operation and SupportHow the system is run and monitored. How problems are diagnosed. Housekeeping tasks. Data archiving.
- Development EnvironmentSetup of tools and environment needed to develop the system. Build and test instructions. Username and password location.
How to Start
Start by imagining that you were on-boarding new people to the project. What do you think they need to know? Create answers to those questions and build up the documentation as you go. Make sure everyone is involved and above all remember to keep it light, exposing the essential details.
Don’t forget the documentation.
Can’t Add Hostnames and Culture Setting in Umbraco
Error – Hostname Already Exists
I recently had a situation in Umbraco where I wanted to add a “Hostname and Culture” setting but when I clicked “save” I kept getting the error “Domain has already been assigned”. This was in Umbraco 7.2.8
After much searching on Stack Overflow where people were suggesting that I hack the domains table I decided against it since I’m using a Production system with no access to the Live database and no easy way of recovery without filling out oodles of paperwork to get Operations to undo my errors – embarrassing to say the least.
The Solution
Finally, I realised that Umbraco wasn’t lying to me. The domain name was being used. I had a previous content page which was similar to the one I was editing and it used the domain name but it had been deleted. It was sitting comfortably in the “Recycle Bin” and when I removed it from there my problem was solved.
Lesson learned – clean up your “Recycle Bin”!
UPDATE – It seems that Umbraco 7.5.4 has an improved error message that indicates where the duplicate is.
When Umbraco Deletes Go Wrong
Deleting Files in Umbraco
I recently came across a situation where one of our Umbraco editors had to do some work for a client. The client had some financial information contained within PDF files that were loaded into the media folder of their Umbraco site. This information had become outdated or linked to newsletters that were no longer relevant or even on the site.
The client had stumbled across the documents while doing a Google search on their site and asked our editor to remove the items, which the editor promptly did. However, a few weeks later the client did the same Google search and found the documents still available. Eeek! Needless to say the client wasn’t happy and we looked foolish.
What Went Wrong?
It turns out that while our editor did a straight forward file delete and the link was gone, the associated file was still languishing in the media folder. This happened because Umbraco, effectively, does a soft delete and puts the media item in the “Recycle Bin”. The associated media files are only actually deleted when the “Recycle Bin” is emptied (or the specific item is emptied from the “Recycle Bin”).
Once we realised this, we were able to remove the offending files and they were no longer accessible from Google (Google still held them in it’s index for a few days until it crawled the site again).
The Fix
The moral of the story is “empty your Umbraco Recycle Bin” when you’re deleting.
My other post about duplicate hostnames is also a symptom of this.
