Eight yoga exercises for better release notes

Corresponding service: Software documentation

About to deliver your next software release? Congratulations on getting another round of good, hard work done. Now you just have to quickly write up the release notes. And it’s this "just have to quickly" that is the problem. Release notes are often written just before the final whistle. But unfortunately they are a necessary part of the release. Sometimes what you end up with is a release note hastily put together and full of jargon. And lots of perplexed users.  

But what does that have to do with yoga?

As you probably know, we practice yoga to find rest, slow down and, if it goes well, get a clearer view of what is important. And that's what release notes are all about: the essentials. So get to it and roll out your yoga mat while I do a quick back lunge: 

What are release notes? 

Release notes offer an overview of changes, improvements and bug fixes and are published together with a new version of a software.

Now let’s get started: with eight yoga exercises (asanas) and lots of yogi tips for better release notes. 

1. Tadasana – Mountain Pose. For a strong structure

In the Mountain Pose we find inner peace, feel as strong as a mountain, and have the feeling of standing with both feet planted firmly on the ground.

Your users also have both feet firmly planted on the ground. After all, they read your release notes for a reason: find out what has changed and if the changes are relevant to them. Most people will therefore only briefly skim through the release notes.

So make your release notes one that readers can "fly over". To do so, you should structure them well and mark important keywords in bold.  

Yogi tip: Use categories, headings, lists, and paragraphs to create a structure.

Yogi tip: Distinguish between features and bug fixes. List new functions in "Features". Error solutions belong under "Bug fixes".

Example 
Lines for carriage information on transport orders | Feature
You can now print lines with carriage information on transport orders. In the Transport Order tab, we added the check box Carriage Info. When you activate Carriage Info, the software prints the information on the weight of the goods on the transport order. 

2. Anjaneyasana – Low Lunge. For better headings 

The Crescent Low Lunge provides better coordination and concentration and helps you feel your physical and inner strength. Get into a low lunge, raise your arms, and feel the power of the headings. 

Some release note authors want to include as much information as possible in the heading . And since text usually comes after a headline, they repeat the text from the headline, only in more detail.  

Yogi tip: Choose a heading that says what you have changed or what is new. In the text below, describe how users will use or access the new feature.  

Example 
Creating links simplified | Feature 5698 
You can now create links more easily. Select the text, right-click and choose Create Link from the context menu.  

We also sometimes read that bug 8976.1 was fixed in version 3.4.1. As the author of the release note, you probably know what is meant – but it's probably all Greek to the users.  

Yogi tip: Formulate headlines that your readers will understand, for example "Image preview problems fixed | Bug 3489".

3. Bhujangasana – Cobra. For a direct approach  

The Cobra may feel a little uncomfortable at first, especially if you have back problems.

Also, addressing your users directly might be a bit unfamiliar at first, but I promise you, it's worth it. Your release note will become more personal and your readers will feel understood.  

Yogi tip: Use active phrases whenever possible and avoid passive constructions. This will also make your sentences shorter. 

By the way, the release notes should be about the added value for the users, not so much about your product or your company. Make it clear that your customers will benefit from the improvements.  

Yogi tip: Avoid sentences with "we" or "company xy".  

Example 
Automatically save changes to files | Feature 0123
Changes to the files in your cloud are now automatically saved. Upload your documents to the cloud and edit them there directly. You no longer need to store your files locally and upload them separately to the cloud.  

4. Balasana – Child Pose. For clear and comprehensible language 

Kneel on the floor and sit on your heels. Close your eyes.

Now put yourself in your users’ shoes and try to imagine what they know, or better still, what they don't. Forget for a moment your expert knowledge as a software developer or product manager. Write as simply as possible, clearly and understandably – and above all avoid technical jargon. You know what a patch is, so do I; it’s just that some of your users might not. You though now know what Balasana is. 

Yogi tip: Use simple, clear language and speak the users’ language. Write sentences that are as short as possible, avoid jargon and terms that are very technical.

Example 
Instead of "New algorithm in the backend for project costings", write an understandable, short sentence with no technical terms: "The total cost of your project will now be calculated automatically." 

5. Setu Bandha Sarvangasana – Shoulder Bridge. For better visualization 

The Shoulder Bridge benefits both body and mind. Bridges can connect what belongs together. And it’s the same for text and images.

Yogi tip: Place screenshots in your text whenever possible. This will improve comprehensibility, especially for longer and technical explanations. 

Example 
Better understanding with line focus | Feature 983-12 
You can now navigate through a document line by line, without distractions. Adjust the focus to display one, three, or five lines at a time. 

6. Virabhadrasana I – Warrior I. For strong references  

Warrior I and II are my favorite yoga poses. I immediately feel so much braver when doing them. You too can become a brave warrior! In Warrior I, stretch and strengthen your legs and open your chest.  

Open your release notes. Refer to existing documentation or other product information and make them stronger. In many cases, you are extending or customizing an existing function. And since your product surely has excellent documentation, add a link to the corresponding topic in the documentation straight away. Your readers will thank you.

Yogi tip: Refer the reader to additional documentation or product information from your release notes. 

7. Virabhadrasana II – Warrior II. To check and be honest 

Warrior II also stretches and strengthens your leg muscles. At the same time, you open your arms to the side and yourself to the world around you.

Be open to criticism: have your release note proofread before publishing, preferably by people outside your area of expertise. And be honest with yourself: ask yourself if you would read your release note yourself.  

Yogi tip: Get out from under your shadow and let others proofread your release note.

8. Shavasana – the final relaxation  

You did it! Now we come to the relaxation part. If you have read this far, you've accomplished quite a bit. With Shavasana you're giving your body and mind the longed-for rest.

And as you lie on your back, stretch your arms out beside your body, and close your eyes. I'll whisper a quick, calming closing tip in your ear: think of your release notes as an opportunity to showcase the results of your work. With well-written release notes, you will engage users, increase enthusiasm for your product, and even reach new audiences.