Shwetha Madhan, VMware
January 15, 2020
As an information developer at VMware, I write all kinds of technical documentation – including the Workspace ONE UEM release notes. To create these release notes, I pull together new feature blurbs crafted by other writers and consolidate all of them into a new document. When I took over this task a few releases ago, I observed a common pattern. All the “What’s New” blurbs had a classic stand-up language: “Added support for XYZ”, “Added X and Y field under Z”, and so on. I wondered — why? Why is the text treating me like a robot? Do real people talk like this? During a stand-up, it’s normal to talk directly about the code that is written, but that information isn’t particularly useful for the end-user. Stand-up verbiage only results in opaque, impenetrable content.
I get paid for the text I write. But I often wonder if customers read and like what I write. Creating content that resonates with our readers is an often-overlooked part of our job. It’s one of those niche skills that not many talk about it. But it’s incredibly important and it can be difficult to do. Besides, release notes are one of the user touchpoints that most of us ignore or pay less attention to. Mostly release notes are treated as an afterthought or even a chore that most of us put off until the last minute. But in a SaaS-paced world, release notes represent a key point of engagement with customers. It is one of the pivotal pieces of documentation that tells our current users why the new release is important to them and at the same showcase our product to the potential users. While it might sound straightforward, writing release notes is an important task that requires more skill, care, time, and attention than it is given.
As a release notes wrangler, my first stop in researching the art of writing great product release notes was, of course, Google. I found encouraging rumblings in the industry about making release notes more engaging, and information about the great benefits to doing so. Several other companies are starting to value and understand the importance of release notes and use them as an opportunity to communicate with the customer base. Slack, for example, thinks release notes are an excellent opportunity to create engaging content that deepens the relationship with their customers and make them easy to understand.
As I started to take up this task more seriously, I recognized a strong need to make our release notes more useful than the default. When I began to postmortem our “What’s New” section, I felt like I was reading an elevator pitch by a robot. The content was boring and too technical, and it deserved an upgrade. As a data-driven writer, I asked myself a key question: Do people even read our release notes? I was surprised to learn that even though release notes are just one percent of the entire VMware product documentation, they have 14 percent of the glory. Fourteen percent of our product documentation views come from release notes. Data analytics provided us the key performance metrics and made us realize the importance of release notes to our users and the need to write useful product release notes. The Workspace one UEM team decided to upgrade its classic robotic style and launched the new SaaSy style.
Our formula for SaaSy style is simple — Collect all the technical facts, strip the jargon, use plain language; and make it nothing less than useful. Our MVP focuses on “Why?”, and we aim to transform the classic stand-up style to a more customer-centric one that focuses on what the product does for the end-user, and why it matters.
Striking the right tone of voice
We wanted our release notes to generate buzz in the customer community about the new features. To create the buzz, release notes need to be shareable and share-worthy. We tried a more conversational style to replace the robotic style we had previously used.
Conversational release notes, in short, active sentences generate more buzz and make sharing easier.
Release notes are supposed to show users what the new version of the software will help them do. For example, a brief use case for a feature is a very engaging way to describe a function the feature performs, and it helps users imagine themselves using the feature in the real world. Carefully done, the note loses none of its accuracy but feels more applicable and relevant.
Here’s an example from one of our release notes:
SaaSy Style—Worried about distracted driving? You can now prevent application notifications from showing in CarPlay mode for all your iOS 12 devices.
Some useful recommendations
- Plain Language is for everyone, even experts: Plain language benefits everybody, from expert readers to international users and people who use English as a second language (ESL). Stripping away the technical details can help you spot the plain language pattern. Try writing your new features as if you were describing them to a friend.
- Judiciously loosen your grammar to increase clarity: Within the boundaries of communicating your meaning clearly, there is room to be less strict with the rules of grammar when you are aiming for an informal tone.
- Be cautious of humor: Humor can create extra barriers to understanding. Humor can be used sparingly to great effect but given the difficulty of writing it well, especially under time constraints, it’s better to avoid. Also, humor is one of the hardest things to translate.
Our title was hurting our SEO
Part of improving our release notes meant, for us, improving our SEO. I worked with our content strategist and focused on a simple form of keyword research called AnswerThePublic, which is a free tool that lets you plug in a starter keyword and spits back all the common search variations that included that word. We found that no one was looking for Workspace ONE UEM Release Notes. Why? Workspace ONE UEM got rebranded from AirWatch years ago, but AirWatch remains active in searches. Our title Workspace ONE UEM Release Notes was unknowingly hurting our SEO. How did we fix this? We changed our title to “Workspace ONE UEM – Powered by AirWatch”, and we made ourselves reachable.
The impact of the media
All communication with customers boils down to engagement—whether or not customers are interested in what you do and say. Revitalizing our release notes has been part of an effort to make customer engagement a higher priority for the Workspace ONE UEM information experience team. Along the way, we found two other easy wins for creating engagement:
Web audiences consume media in more ways now than ever before. By speaking to readers in the mode and medium they prefer, we can propagate our message effectively. Embedding product release videos in release notes boosted our SEO ranking.
- Social media
Social media lets customers advocate for you if they are interested in your product and message. Adding social media plug-ins to release notes became an easy way to raise awareness and increase the reach of our release.
Did it work?
We pulled the first month of data from the Google Search Console and Adobe Analytics for the last “old style” release notes and our first “new style” release notes so we could compare apples to apples. Even after just one month, we saw a 2189% increase in impressions, a 707% increase in clicks, and a less dramatic but still impressive 39% increase in page views. The massive increases in clicks and impressions show that we made the release notes much easier for our customers to find. We have a captive audience so it’s not surprising to see page views have a less dramatic increase.
Meeting the customers where they are with the information they need, presented in a tone that appeals to a wider variety of readers, we crafted customer-centric release notes and got them into more customers’ hands. “Customers make it possible” is a sentiment at the core of VMware’s mission. Our innovative products free customers from constraints to allow them to meet their toughest technological challenges. As Information Developers, it is our responsibility to help customers understand the product capabilities and experience our new features. Engaging, customer-centric release notes create a compelling user experience, and they also let each user pass on that experience to an even wider audience.
In conclusion, the next time you think users aren’t sitting there waiting for updates, you could be wrong. Even the most minor changes can provide a unique experience to your product – and people are noticing. It is up to you to get the voice and balance that is right for you and your brand. But it’s worth a little extra time and effort if your release notes provide users with meaningful and informative content.