Category: written communication

Tips for Writing App Release Notes

The iOS, and I assume Android, platform provides us with a few precious characters for each release. There’s no guarantee a user will read them, but, if they do, you had better make sure that you’ve treated that space with the utmost of love and attention and filled it with amazing words for your users!



Will anyone read them?

Like this page, maybe, maybe not, but the better question is:

How will I show the user that I genuinely care about their experiences and goals when using my app?

So what do I write?

This is a good time to think about what action you want to invite the user to take in this revision of the app. Think about their experience. What action are you enabling them to do? How does the new functionality further your users’ goals?

Can I use humour?

It often depends on your voice and tone guide (if you have one), but irrespective of that, there are still some guidelines you can use.

  • Don’t belittle the user, ever

  • Don’t downplay a bug fix with humour, especially one that has caused a lot of challenges

  • Be careful of localisation, humour rarely translates well

  • What sounds funny in your head might not be funny on paper

  • Stay away from stereotypes, they never end well

How much detail should I go into?

I think some writers struggle with this because we all love words. However, by prioritising and layering the information you can give your app shiny release notes that your users will get value from (which will give you a warm fuzzy feeling too).

You get a couple of lines to tell your user why they should click more, make it count!

The Important Stuff

  • This is the bit of text the user can see without scrolling irrespective of the responsive display.

  • This should be the information that is most important to your users.

  • Don’t put placeholder or arguably pointless text here like
    “Thanks for using the app!”
    “We’re always looking for ways to make things better”
    “ We release every two weeks!”
    “Thank you for your helpful feedback”
    “Bug fixes” (we know you fix bugs)
    That’s precious space you’re filling with words that have no value to the user or your app!

Questions to ask yourself:

  • What is the one thing your users will care most about in this release? 
  • What action do you want to invite them to take?

Examples



Wahoo Fitness does this really well. Right at the top, they list chunky new functionality (who doesn’t love an integration?) and there’s more!



tips app release notes wahoo more.png

‘More’ Additional Detail

This is still contained within the app release notes but can only be seen by scrolling or clicking ‘more’.

Questions to ask yourself:

  • How does the new functionality help them achieve their goals?

  • What have you done to smooth the experience of the app?

  • What did you fix for them, specifically?

Staying with Wahoo Fitness, clicking ‘more’ tells you what’s been updated and improved. The information is likely prioritised according to the user’s needs and provided in a succinct and clean way.



tips app release notes telegram.png

‘More’ Additional Detail Continued

Another app that does this very well is Telegram Messenger. It is nicely formatted and spaced. In addition, it has been written with user goals in mind.



tips app release notes trello.png

‘More’ Additional Detail Continued

And lastly, I want to give a shout at to Trello because I think someone who really cares about the users wrote the release notes (as you might expect from an Atlassian company!):



tips app release notes pluralsight.png

Everything Else

This is right at the bottom of the text and is usually 1–2 lines that can signpost the user in case they have another query.

Questions to ask yourself:

  • Is there any other relevant release information such as compatibility?

  • How can the user get help, support or contact information?

One company that I think nailed it is Pluralsight. They’ve given the most important stuff first and followed it with what they’ve improved. They’ve given details about the bugs and signposted the user to an email address if required. Nice work!

Summary

  • Write with the user goals in mind, always ⚽

  • Give the user the right level of detail in the right place at the right time ✍️

  • You have limited space, make every character count (check out your voice and tone guide) 🔡

  • Consider signposting the user at the end of your app release notes ➡️

  • I personally think we can do away with stating things like “bug fixes” unless you’re going to give details on which bugs. All software companies fix bugs 🐛

Technical Writing – Everyone’s an Expert

I was driving to see my Gran the other day musing over recent events when what I can only assume was a Pterodactyl flew across my car, depositing on my windscreen at least three days worth of breakfast, lunch and dinner. I’ve since had to top up my screen-wash.

You know the drill, you’ve spent hours composing what you consider to be beautiful instructions for the product to assist the user in their hour of need. You’ve gone through all the review gates (that you likely set up) and you’re ready to go live.



tw everones an expert seagull.jpg

And then in comes the expert with their swoop and poop. They read your pride and joy, they glance over who’s reviewed it (if you’re lucky) and then they offer forth their opinion, after all, it’s just some words — everyone’s an expert in those!

You don’t see this with code (usually).

You have PRs, someone reviews it, any changes are made and then the PR is approved. Fortunately, not everyone thinks they’re an expert in Java, which is most definitely a good thing! However, words aren’t afforded the same level of respect, everyone can do words, right?

Deep down, during the aforementioned fly-by, you’re cringing. You want to pull up any number of Hemingway quotes, and wave them about, as well as and stamp your feet (maybe just me). Instead, you sigh, make the requested change (because it’s easier than fighting your corner), and then you likely begrudgingly send it back through all the revision gates because what choice do you have?!

So how can you perform a preemptive strike on potential swoopers and poopers (aka, stakeholders) and what can you do if it’s already happened?

Image by Engin Akyurt from Pixabay

Identify your stakeholders

If you’re new to the business or the role, identify your stakeholders, include them early and get them on board. Find out from your colleagues who is a closet Technical Writer and who always has an opinion as well as the regular list of stakeholders that you’re expecting to work with.

You need to identify their drivers, what makes them tick. Have they been left out in the past? Do they feel like they need to “add value” in all areas of the business so they swing by ‘cos words are easy? Do they want to be you? Do they like to have fingers in all the pies? You have to talk to them!

In fact you have to talk to everyone, leave no stone unturned in your hunt for stakeholders. You need to check behind the sofa, under the rug, and most definitely in the box room. You don’t need to make everyone a reviewer (no one has time for that), but you do need to identify the people that not only care, but are in a position to give a sign off on your creations.



tw everones an expert parrots.jpg

Not all of these stakeholder challenges are easy to solve as many of them are outside of your circle of influence if you take them at face value.

However, this is where your skills of taking people on the journey are absolutely invaluable.

Don’t make them all be a tick box quality gate (although some will be just that), instead ask for their opinion early, show that you value their advice, build their trust in you and your ability to do the job.

Stakeholders who have been allowed to invest their time and energy in the creation of the content will become your biggest advocates. Elevate them and enjoy the extra pair of eyes that you control on your timescales.

Image by Vinson Tan ( 楊 祖 武 ) from Pixabay

They still swooped and pooped! 💩

Okay first up, we’ve all been there, do not have a pity-party. It does no one any good and just serves to make you wallow in your own pit of gloom, eat pizza and get that really judgemental message from Netflix.

Instead, pick yourself up and ask yourself why the fly-by happened. I bet that if you really soul searched you could find something that you can directly change and influence that would dramatically reduce this from happening again.

However, we’ve covered that. So now it’s happened, job one (we’re not doing that pity-party remember), clean up! Now I don’t mean like a Roomba would when the dog deposits a gift in the kitchen; don’t go smearing it everywhere. Instead, graciously pick it up, examine it (I am regretting using this analogy now), deposit it in the nearest bin, and wash your hands (‘cos, eww gross).

Now you need to engage with the pooper to explain what you’re going to do to address not only their concerns with your creation, but future ones. For this one, I strongly recommend that you try and avoid jumping into defensive mode. Signs that you’re in that mode include the urge to explain your processes, justify your methods or wave other reviewer’s feedback at them. If you find yourself there (we all have, I certainly have), take a step back and ask yourself what you want from the situation. What you want is a stakeholder that is your ally early on in the process.



Instead of being the defensive Technical Writer who feels like they now need to justify their efforts, try having an open conversation of asking them why they gave you the feedback, and then keep asking why (in a non-aggressive way). Keep drilling down until you reach the source of their pooping ideology. Channel your inner two-year old self that drove your parents mental with your constant questions.

Once you know the source of their pooping ideology you’ll know what to do with the gift. It may be that while delivered poorly, the feedback is actually crucial and needs incorporating for reasons you didn’t even realise. It may be that they know something you don’t and while it doesn’t need rehashing this time, their ill-timed feedback will save you a lot of pain in other projects.

Alternatively, it may be that they just can’t help themselves, in which case early involvement will likely save you a lot of pain just before release day.

Image by TheOtherKev from Pixabay

When all is said and done, stakeholders who review your content (invited, or otherwise) are both your biggest advocates, and at times, your worst nightmare. Take a step back, ask why they’re giving the feedback and then turn it around so it’s on your terms next time. It’s your content, you’re the Technical Writer. Own it and accept that it is, and always will be, a shared vision.