3 Key Elements of a Good Release Note

As a programmer, we spend a lot of time and effort on releasing a build. You made sure that everything works fine and is well-tested before it is sent. You expect that your hard work is seen and appreciated. You send the build along with a few lines of notes on the build. However, you get a response with a lot of questions, things are not working as you expected. Assuming that nothing was wrong with the build, did your release notes convey the right information? or enough information to test it?

Release notes are very important documents. They have one single objective. They are often not given importance by the developers on small to medium-sized projects and this is a critical mistake. Release notes represent a build just like your resume represents you. It’s also not necessary that you write a complete manual or a book to explain your build which is something not mostly feasible on small to medium-sized projects.

Based on our experience there are some key points that you should not miss in a release note.

Include any information that is required to test the build e.g the sample username/password generated for the user so the user doesn’t have to go through registration every time (unless it's the registration part being tested). Even if you shared it in the last release note, I would recommend sharing it again so the user doesn’t have to go through the hardship of finding the last email and then using it. Remember the easier you make it for the user, the better he is going to feel testing your build.

Include any other information like

1. Third-party plugins are required.
2. System requirements to test the build like operating system requirements.

Your project plan clearly states which features will go in which build. However, It is always a good idea to include that in your release notes as well. Just a list of features included in the build is enough for most releases. However, a list of steps to test complex features is highly recommended as most during the development, help instructions in the projects are not completed till the end. This sets the expectations of the user right and there is no disappointment in checking the build if some specific feature that was expected is not found. If a feature is not 100% complete in the specific release, do mention it explicitly as well.

It is always a good idea to send the user a build that still has some small but known issues which are not deal breakers so that the user feedback can start coming in and time is saved. However, not including that in release notes is a bad idea. A list of known issues along with pointers to links in your bug management software or your bug document is very important. This sets the expectations of the user before he tests the build and they never mind known small bugs or issues.

Apart from the above issues, I believe just a good MS WORD spell check is recommended. It just highlights the fact that we were careful about even minor details.

A good release note sets the right expectation for the user and results in positive feedback and a sense of entitlement in your customer especially if it's a new customer. A good release note however won’t save you from a badly tested build. It will just make your well-tested build look better.