Re: Release note Q

Subject: Re: Release note Q
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 16 Jan 2020 08:03:42 +0000 (UTC)

For us, RNs answer specific questions:* WHY should I update (fixes & improvements)?* WHAT WILL HAPPEN if I update?* Is there ANYTHING I NEED TO KNOW before I update (compatibility and known issues)?
* DID YOU FIX my pet issue?
We also have enterprise customers who are prohibited from updating without accompanying RNs, so they sometimes serve a legal-ish purpose.

The field asked us to include the What's New info for the given release family... A Mktg-level list of our new features. So we include that as well (thank you DITA and conrefs!).Â

As we move to a SaaS model, the RN questions will change. In that model users don't have a choice about updating, we do it TO them (erm... FOR them). So the RNs answer one primary question... WHAT just happened? In that model, the RNs are the primary place to deliver What's New info, but I suspect online help can also give a What's New history of the product in a top-down list of expandos. I suspect we will not include that in the PDF.Â

We do repeat the compatibility info. If you think about it, you have no guarantee of any context the user might have when coming to the RNs. At any time, THIS release of the RNs could be the first RN that the user has seen. So referring to previous ones as a way to avoid boilerplate is not really an option IMO. The only case where we make that kind of reference is for a super-mini release... say version 123.45.2. Then the RNs might be for one specific fix for one specific customer. In that case we just list that single fix, and say (effectively), "Please refer to the full 123.45 RNs."

BTW, I'll be presenting our RN process on Feb 11 for Learning DITA Live --
Release notes: Transform JIRA queries into DITA reports

Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: Re: Ig Nobel documentation
Next by Author: Re: Best business arguments for online help?
Previous by Thread: Re: Release note Q
Next by Thread: Re: thought leadership content

What this post helpful? Share it with friends and colleagues:

Sponsored Ads