Eight yoga exercises for better release notes

by Uta Lange on July 04, 2022

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.

Zwei Yogis praktizieren Tadasana, Urheber: Andrei Rybalko, Quelle: https://de.123rf.com/
Two yogis practicing Tadasana, created by: Andrei Rybalko, source: https://de.123rf.com

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".

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. 

Yogi-Frau praktiziert Anjaneyasana, Urheber: goodstudio, Quelle: https://de.123rf.com/
Yogi practicing Anjaneyasana, created by: goodstudio, source: https://de.123rf.com 

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.  

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.

ogi-Mann praktiziert Bhujangasana, Urheber: Andrei Rybalko, Quelle: https://de.123rf.com/, Ausschnitt
Yogi practicing Bhujangasana, created by: Andrei Rybalko, source: https://de.123rf.com, detail

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".  

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.

Yogi-Mann praktiziert Balasana, Urheber: Andrei Rybalko, Quelle: https://de.123rf.com/, Ausschnitt
Yogi practicing Balasana, created by: Andrei Rybalko, source: https://de.123rf.com, detail

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.

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-Frau praktiziert Setu Bandha Sarvangasana, Urheber: Lio putra, Quelle: https://de.123rf.com/
Yogi practicing Setu Bandha Sarvangasana, created by: Lio putra, source: https://de.123rf.com 

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

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.

Quelle: https://support.microsoft.com/de-de/office/neues-in-word-2021-für-windows-8f0b9117-8cf4-4677-8cd5-d848dd0e1ac9#:~:text=Word%202021%20für%20Windows%20ermöglicht,wie%20Punktradierer%2C%20Lineal%20und%20Lasso
What's new in Word 2021, release note example introducing line focus, source: https://support.microsoft.com

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.  

ogi-Mann praktiziert Virabhadrasana I, Urheber: Andrei Rybalko, Quelle: https://de.123rf.com/, Ausschnitt
Yogi practicing Virabhadrasana I, created by: Andrei Rybalko, source: https://de.123rf.com, detail

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.

Yogi-Mann praktiziert Virabhadrasana II, Urheber: Andrei Rybalko, Quelle: https://de.123rf.com/, Ausschnitt
Yogi practicing Virabhadrasana II, created by: Andrei Rybalko, source: https://de.123rf.com, detail

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.

Yogi-Mann und Yogi-Frau in Shavasana, Urheber: Andrei Rybalko, Quelle: https://de.123rf.com/
Two Yogis in Shavasana, created by: Andrei Rybalko, source: https://de.123rf.com

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.

Add new comment

Your email address will not be published.

You might also be interested in

What do yoga and release notes have in common?

July 04, 2022

Uta Lange is a technical communicator and practicing yogi. In her latest blog post, "Eight Yoga Poses for Better Release Notes," she draws inspiration from yoga asanas to improve release notes and make them more user-friendly. more...