Release Notes as an in-class-by-itself documentation type

Release Notes can be characterized as a way of formal written communication within the development team, between the development team and management or software users. Very often, the true value of the Release Notes documentation is WAY underestimated, and in this article, I shall prove its genuine worth.

First of all, I’d like to mention that there are no solid rules or firm conventions established for producing this kind of documentation deliverable. Its layout, components, and scope are totally negotiable and can be in various ways adjusted to the project team’s needs and requirements. However, the message Release Notes deliver and the purpose of generating them are always static. Nevertheless, there is a vital aspect to consider when producing Release Notes – the audience, and it may surely vary.

Release Notes serve to inform of the changes that a particular version of the software has undergone since the previously released version.

Now, we have made it clear that the message about the changes needs to be conveyed to the reader, however, how exactly should that be done? Which vocabulary are we supposed to stick to: technical or rather general? How detailed are we supposed to be when lodging new features against users? Does this known issue need to be included and notably emphasized, or shall we better omit it? (It is advisable to stay completely honest with your audience, though).

The answers to all those questions above usually get undimmed as soon as you identify your audience.

So, your audience might be end users and customers who have no clue of all the back-end technical prospect of the software you deliver. Well, they do not need to, as the primary interest of theirs is concentrated mainly on the functionality and the experience it brings forth. Therefore, the key to convincement to upgrade the version of the software is, obviously, the description of the features that impact directly user experience.

For instance, we would be pleased to announce to our end user that it has now become possible to subscribe to our latest newsletters omitting a tedious procedure of creating a profile, as it was previously required. This would be our biggest new feature and functionality released in this version, and we are extremely proud to give our users an opportunity to both save time and still be aware of the greatest offers we can suggest on the weekly basis!

That is it. They do not need to be aware of the fact that to implement that new functionality, developers have been sweating painstakingly over the hundreds of lines of code for two weeks and elaborating the whole process dependencies between the internal integrated systems; or that the front-end guy has added a couple of supplementary landing pages; or that the localization keys have been changed and made configurable.

However, this kind of changes ­– changes on the technical side of the software development – is of the same value as the ones affecting the end user because these changes are to be documented for the management, the development team, and customer support.

The true value and purpose of generating Release Notes for your development team, tech support department, and management, in other words – the internal Release Notes, is justified by the following:

  • The management can monitor the overall progress of the development and whether the development team’s performance results meet the initially agreed terms and collaboration requirements.
  • The technical customer support team is aware of the modifications and possible issues that may occur on the back-end side and, therefore, how to fix them later after the release takes place.
  • In the development lifecycle of some teams, Release Notes are generated between the development and testing phases and appear to be the main documented source for test engineers to rely on when getting down to searching for bugs.
  • Release Notes documentation is kept for logs with the help of which the development and administration teams can always make sure they are on the same page.

Eventually, this is an irreplaceable kind of documentation deliverable that summarizes all developers and test engineers’ hard work performed within a particular sprint and demonstrates the scope of the tried-and-tested and successfully (or erroneously) deployed features.

Stay tuned and get to know more about the internal and end-user types of Release Notes, their purpose, components, and other peculiarities in the topic follow-up soon.


One thought on “Release Notes as an in-class-by-itself documentation type

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s