What Matters In Patch Notes
“Thinking is an expedition into quietness”
I worked for several years at a major tech company in Russia where I spent a substantial amount of time writing copy in English. Prior to that I edited copy at more than one news organization. “Copy” is media industry slang for any public-facing text that appears in print, online or on a screen. Some places lean on tomes like The Associated Press Stylebook for general direction on how to write copy, and many have their own internal style guide specific to whatever media is being written about.
One of my mentors at said tech company was the de facto style guide in both Russian and English and was utterly fearless. No topic was outside their understanding, be it cloud computing or corporate comms. They were the rare sort of person who had infinite patience and energy to respond to those who claimed to know how copy ought to be written, and zero tolerance for anyone unwilling to learn otherwise. However, so long as you wished to learn, they would unfurl their knowledge to you, but it was never done in the way where they told you what to write. Instead, the emphasis was always on learning the principles behind the text.
To that end I’m going to pass on some of their lessons. Consider this a follow up from the previous post but we’re going to focus on patch notes. I’m not going to tell you how you should do your patch notes, but I am going to tell you how and why I write copy the way I do.
WHAT ARE PATCH NOTES?
Patch notes are frequently recurring texts seen in a variety of applications. They can often be dull, such as the Gmail app for your smartphone…
…to borderline unhinged, such as the podcast app Pocket Casts.
Patch notes are also seen in video games. For example, Street Fighter 6 recently put out lengthy copy for what it calls a Battle Change while Stardew Valley uses the term “Changelog” in its patch notes on Steam.
You might have noticed that on the iOS app store these things are usually written under the heading of “What’s New”, which are two key words here. Call them patch notes, changelogs, system updates… whatever is written under this heading should be whatever is current.
WHAT IS “WHAT’S NEW”?
Stylistically, this means we are in the present. This means we do not need to repeatedly write that we can “now” do a certain thing because we are already capable of it. The application is in the hands of the person using it. Therefore your job as copywriter is to tell them what they do with it.
Another parasite phrase that typically creeps in at this point – either out of apparent desperation to create some sort of narrative behind a dry subject or to alleviate potential criticisms of what came before – is “no longer”. There are two big reasons to ditch this phrasing.
The first is, assuming your patch notes are correct and reflective of the state of the application, then no one needs to know any of what came before especially if it’s not even there anymore. Due to the nature of how most games and apps are distributed, you are also unlikely to even know what level of familiarity readers have with your product. Assume everyone coming to your patch notes are complete newcomers.
The second big reason is, as per the Zinsser quote in the previous post, the forces competing for the reader’s attention are many and they are all noisy. If you want a more contemporary version of what this is, listen to the former Cracked editor Jason Pargin (AKA David Wong) talk about the phenomenon on their tiktok.
Tiktok failed to load.Enable 3rd party cookies or use another browser
So do your readers’ senses a favor. You’re already at a disadvantage in the so-called attention economy, you don’t need to further kneecap yourself.
FIGURING OUT WHAT’S IMPORTANT TO WRITE
Do not confuse “new” with news. Your copy might be going out to a “global” audience, but that audience is atomized. Going by hardware surveys, you should know they are reading your text from the comfort of their desks or mobile devices. Even if you are working for one of the biggest companies in the world, you should lean on this intimacy afforded by the medium because it gives you an advantage over other media. Side note: this is one reason why the Gmail patch notes screencapped earlier are aggravating to me professionally as they show contempt for both their own product and the audience.
Centering your text around the imagined user gives you a framework upon which to write. This framework has the following guidelines:
“You” and not “We”
Imperatives over nouns
Avoid negative constructions
Human-readable text; no jargon
Emphasize new or existing features
Remove anything not visible on the frontend
“You”, yes you. The person reading this. That’s who I’m writing to, though it should be noted that I would not explicitly write within a text that I was writing to you. Instead the point is the text tells you what You Can Do.
This is where your imperatives come in. Verbs or phrases that command the reader what to do. Collect. Discover. Visit. In other words, your Calls To Action.
While you are telling your audience what to do, avoid telling them what not to do (this goes in the same bin as “no longer”). This practice isn’t exclusive to this sort of writing – I hear it frequently during classes for dance or for yoga and its purpose in these scenarios is to encourage you and your classmates to do the thing that is being asked, be it a pivot or a standing bow pose. The best kind of teachers do not tell you what not to do – they will wordlessly scrutinize your actions and push your focus towards what they think you can do.
Be mindful of slang or highly-specific terminology. Does your audience know what a finite state machine is? Do they care? Another side note: do you? If you don’t know what you’re writing about, the audience can tell, even if they can’t adequately explain why. Finding out what a single sentence you got out of a commit log means might take you an entire afternoon of messages, calls, and maybe reading a few articles. Yes, this is the job.
Once you have figured out who you’re talking to, what to say, and how to say it, make sure it’s relevant to the thing you are writing! Patch note paralysis, or the inability to tie whatever is “new” to the thing we are writing about, can sometimes creep in. However, this is the exact point where we can lean on the existing features. Maybe X is twice as fast since the update, maybe the visual design of Y got reworked so people could actually find it this time around. It’s where you get to re-sell existing things about your app or service to the person reading.
The last point in this user-centered approach is for the copywriter to assume they are in the user’s shoes, using the same thing. Anything that changed in the backend that isn’t reflected in the frontend doesn’t get mentioned. Oh, the codebase has been updated to streamline build deployment?
Only mention anything the end user can explicitly see or interact with. Anything else is a waste.
NO CLICHÉ
Blasting from the past, clouds and their silver linings, better late than never, and all that jazz. The obvious reason not to use these things is laziness.
A less obvious reason is the erroneous assumption that your audience is all well-educated native speakers from North America and Western Europe. Figures of speech might be all well and good in English, but English is not the most spoken language in the world. Assume that your copy might end up being reported on or regurgitated in another language or territory altogether.
But an even less obvious reason, and one that can cause incredible damage, is that clichéd words or phrases might have extremely questionable origins that might not set off any alarm bells at first blush.
Tiktok failed to load.Enable 3rd party cookies or use another browser
So scrutinize what you are typing and why you are typing it out. The drone of the world’s 24/7 news cycle is inescapable and certain catchphrases, especially during election cycles of particularly prominent countries, become background noise. This is not to say that some copy deliberately ends up resembling dog whistling for a fringe group; it’s that language develops in such a way (sometimes very quickly) that those words or phrases can quickly enter the mainstream.
AVOID REPETITION AND GET A THESAURUS
Or go to thesaurus.com. Like style guides, dictionaries and thesauruses are tools of the trade. Use them, especially if you don’t have an editor.
READ IT OUT LOUD
Even if it’s only ever meant to be read with the eyes, read it aloud. Does it make sense? Does the rhythm feel right? Or are you so appalled with what’s been typed out that you reflexively hit Ctrl+A and Delete to start over? If that happens, good. This is how we write better copy.
EXCEPTIONS? IF YOU CAN PULL THEM OFF…
Almost everything I have written above can be turned on its head. Want to write a 2000-word epic poem where others normally put four bullet points? Go for it, but do so competently and from a place of knowledge, and bear in mind the points from the previous post. That means deviating wildly from the constraints of the platform you are posting copy on or what your audience expects out of you can easily backfire.
THERE ARE NO MEDALS
Good copywriting is invisible. Outside of those within the industry who can spot the hallmarks of a good copywriter, the overwhelming majority of people will likely ignore your efforts. Providing the message you have written cuts through the noise and reaches the intended recipient, then the work is done.
[Subtitle quote is Han, Byung-Chul. The Agony of Eros (Untimely Meditations Book 1) . MIT Press. Kindle Edition.]