3 Key Elements of a Good Release Note

As a programmer, we spend a lot of time and effort into 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 is 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 represents 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 which you should not miss in a release note.

Information required to test the build

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 its the registration part being test). Even if you shared it in the last release note, I would recommend to share it again so the user doesn’t have to go through the hardship of finding the last email and then using it. Remember the more easy you make it for the user, the more better he is going to feel testing your build.

Include any other information like

  • Third party plugins required.
  • System requirements to test the build like operating system requirements.

Which Features to Expect

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 mostly 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 on checking the build if some specific feature which was expected is not found. If a feature is not 100% complete in the specific release, do mention it explicitly as well.

Known Bugs or Issues

It is always a good idea to send the user a build which 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 sense of entitlement in your customer especially if its 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.

Author’s Google Profile

Author Barkan Saeed

More posts by Barkan Saeed