After realizing my goto resource would be on vacation during the next big deployment, I decided to step in and take the lead on producing the key product documentation.
Our company publishes Release Notes for every major product upgrade. We create this formal documentation for existing customers mostly, as we look to highlight improvements and bug fixes to our software products and any changes in how we deploy, license, or support those products.
I have regularly contributed to this document but have never owned the task of generating and assembling the Release Notes for our product deployments. With each major product release, I have also looked for opportunities to incrementally improve the structure and details of this important piece of product collateral.
What drove this decision
One of my Product Managers had scheduled some time off of work for a much-needed (but poorly timed:-) family vacation. Up until this time, the Product Team had leaned on him to lead the effort of producing the Release Notes. And he had always come through.
Each time of course, it had been a team effort as each Product Manager was ultimately responsible for capturing and communicating their team's respective work. But "Vacation Guy" had been the one to pull it all together and ultimately deliver it to the eager masses.
His absence would put us in a tough spot - but it also presented a good opportunity for me to pitch in.
The decision: Roll up my sleeves, dust off the technical writing skills and crank out the next iteration of our product release notes.
I was confident about writing the document itself and fully aware of the entire scope of the upcoming release. But beyond the heads-down task of cranking out the words and pictures, I wanted to use this occasion to advance the state of the product communication we use with our stakeholders.
Our new Product Marketing Manager has been pushing my product team to better connect the dots around product/feature positioning.
On a related note, the company had recently hired our first, full-time Product Marketing Manager (a great move) who among other things, is helping us with the many tasks associated with a product release. For example, she has taken over the Release Communication Plan that is used to orchestrate most of the customer-facing tasks like email notifications, blog posts and related content marketing activities, and promoting the post-release webinars. And much of what she requires for this Plan is derived from the initial draft of our Release Notes.
Among the many improvements she has ushered in has been pushing my product team to better connect the dots around product/feature positioning. For example, the work we do to create testable hypotheses further upstream in the product discovery and early development process were all but lost by the time we delivered the working solution. But that is valuable information that needs to be communicated to customers and end users.
Plan of attack
We generally organizes topics in our Release Notes like this:
TABLE OF CONTENTS
About the Release Notes
End of Life Announcements
- Major enhancement
- Customer facing notes
- Content-marketing fodder
- Internal-only messaging
- Major enhancement
- Other enhancements
Getting started was not quite as easy as "Save as, Search-and-Replace" but we had developed a reusable structure for the document that made it easier to produce each new iteration.
Internal first, then external version
I began by creating an internal-only version that contains more information than what was necessary for customers. This initial version provides a diversity of details around each topic and was meant to give our Professional Services and Support teams a better understanding of the impacts, if any for customers.
For example, on the extreme end, I might thoroughly describe the migration steps for users that are transitioning from a deprecated feature to a new enhancement. On the other extreme, I may simply reference existing collateral such as public-facing knowledge articles that are affected by the release and would need to be updated.
I delivered a draft of the Release Notes to the Product Marketing Manager early on so she could start to build the Release Communication Plan. I also circulated it to the rest of the teams to get all the wheels turning for the upcoming release.
More than just an enhancement list
The bulk of the content in the document relates to the product enhancements. Customers (and Sales teams) tend to focus on the shiny new things. I try to accommodate by separating and highlighting the big stories from the much longer list of smaller enhancements.
For each major feature, I started by revisiting the existing customer pain that prompted the product work. Sometimes I even included relevant feedback we received before and during the development cycle.
In describing the solution, I outlined the way the feature is used and included screenshots where helpful. I try to provide at least 1 example to further help orient the user.
With all this information repeated for each big enhancement, the document can often get quite lengthy. To counter reader fatigue, I reuse a consistent layout throughout this part of the document and break up the text with subsections, internal links and generous whitespace to make it easier to consume.
Updates to primary customer narrative
Along with the general description of the major and minor features included in the release, I also posted refinements around our main use case to help the Content Marketing Team rework their editorial calendar to fold in new blog posts, videos, and other collateral related to the release.
The internal notes and supplemental use case-related material is helpful for connecting the dots between customer needs and shippable products but is ultimately stripped from the final, external-facing version of the document.
By most measures, my turn in the driver's seat did not negatively impact our process. I was happy to have made a few, incremental enhancements and as with most product efforts, will be looking for feedback and validation from all stakeholders in the days that follow.
We will go through several internal iterations of authoring and review the Release Notes before we finally publish it externally to customers, concurrently with the release going live. Often, we will work to refine the Release Notes up until a day or two before the release as last minute details are being ironed out. The finished version is deployed on the company website with any number of links from within the product, from support documentation, from the marketing site, and from outbound promotional emails.
Customers have responded positively to the level of information we provide in our Release Notes. I suspect we will eventually move away from the traditional PDF document to a more fluid web/mobile publishing solution. Additionally, we are starting to favor short videos to introduce each major enhancement but they take longer to create and are more difficult to update if/when the screens/pages change.