Importance of Release Notes

Ask yourself - as a Developer who regularly deploy software to production environment - what was released in June 2017 ? The first thought that comes to the mind ? "Release Notes", or Everything is in GitHub ? I bet the answer is latter.

 Over the past decade dynamics of application delivery has changed drastically, from old school waterfall product delivered once a year to hourly deployments by top companies. With frequent application delivery communication must convey the changes, upcoming features to provide best user experience.

 As technology and human life are integrated the need for communication channel between the product and user of utmost importance. This communication channel is "Release Notes". It serves as the best medium via which company can be true about its efforts and address problems in the system. The key elements to be highlighted here are transparency and visibility towards customers. As customer truly appreciates clear and concise message and it shows company cares for its users.

 Imagine one day you go to visit your doctor and ask "could you remind me the medicine prescribed last time" and doctor replies "I don't remember, I lost all the notes on your case" -surely you won't go back to the same doctor ?

 If doctors only talk and operate without documentation it would be impossible to treat a patient and there would be no history of treatment and prescription. If doctor retires or patient wishes to change the doctor is it fair for that patient to start from square one ? 

But they have one central place, i.e. single source of truth, for reference so that next that the next doctor can read and begin helping the patient right away. 

It's patient's right to know what was prescribed by the doctor and impact it has on his well-being.

I draw this parallel as in technology we have a major impact on everyone who uses our product or services in one way or another. Handover of information is the key element and release notes are just the medium to help product owner reach out to their customers right away.

Now with delivering applications with bi-weekly cadence there is a caveat "lack of documentation" and following questions are always raised regarding release notes and would like to address them.

 Why Do We Need It ?

 Single source of truth for all the work done and delivered to the customer.

 Who Is Going To Read It ?

 Everyone ! Business, Engineers, Customers etc - all need to know.

What's The Value ?

Let's say your favorite developer "Tony Spark" won a lottery jackpot and is the only genius on your team. Now all the great work goes along with this one person. Other aspect of this is the On-Call team. They shouldn't have to scramble through emails or GitHub for latest production deployment information.

 In Agile Do We Need Documentation ?

 Seriously !!! you have heard this one before. My humble answer is - do you need a birth certificate ? Common excuse is "we are growing very fast and delivering every 2 weeks in an agile environment". Concept of agile means right documentation which is concise and precise to convey the right message to the customer.

So Keep Calm & Write Release Notes

 It's important and if you don't do it then someday a production incident will remind you of this article.

 Here are some guardrails principles to help you identify the right audience and style of communication required.

•  Clear Structured Human Readable Language
• Visuals, Screenshots and Video Recording
• Avoid PHD Tech Jargon
• Have Excitement In Features Delivered and Show Value
• Be Open About Bugs and Know Issues
• When I look back a year later, What do you I need to know from this release

 One last thing to consider before writing "Release Notes" is to address your brand value and reputation i.e. make them look good as it represents your company.