The Strange Art of Writing App Release Notes

What makes a great release note, according to the authors

4 min read
A photo of a phone on a table showing an app release note on the screen from the Transit app.
Photo: Getty Images; App: Amy Nordrum

If you have an iPhone, go to the App Store and navigate to Updates. You’ll see release notes describing changes developers have made to the newest versions of the apps on your phone.

For the most part, they’re pretty boring:

“Bug fixes and performance updates.”
“Bug fixes.”
“This update contains stability and performance improvements.”
“Update to optimize alert handling.”

But sometimes, a note will stand out. Scrolling through my own recently, I came across this one written for a transportation app called Transit that I often use here in New York City.

A screenshot of an app release note for Transit.

Curious, I tracked down the author—Joe MacNeil, Transit’s in-house copywriter. “I think I mostly got hired to write the release notes,” he told me. It’s actually his favorite part of his job.  

According to MacNeil, Transit considers release notes to be one of its best opportunities to connect with users. “Inside the company, I think release notes are taken as seriously as blog posts,” he says. Multiple drafts are shared back and forth. “The team is really exacting,” he says. “If I have a B-rate joke, they don't let it get out.”  

Release notes are, at their simplest, a way for developers to tell users what’s changed about the apps on their phones. They describe new features and keep users informed about important software changes. And updating apps is good digital hygiene, since new versions fix problems and patch vulnerabilities.

A screenshot of an app release note for Seamless.

Writing release notes can be a pain, though. They’re often dashed off by someone when a development team is ready to submit new code to an app store—essentially as an afterthought. “It used to be the last thing on the list and was not given a lot of attention,” says Rob Gill, a former UX manager at Perform Group, a firm that manages a dozen apps on behalf of clients.

As a result, many app release notes are rather humdrum. They repeat a few generic lines, often variations of the phrases “bug fixes” and “performance updates.”

But some notes—and their authors—show more personality. MacNeil at Transit is one of them. Greg Gueldner, who works on user services for Medium, is another. A few years ago, Gueldner noticed how boring release notes had become. “It’s just bug fixes, everything is bug fixes,” he says.

A screenshot of several app release notes on an iPhone screen, including one by Transit that stands out for its originality.

He and his colleague Nick Fisher volunteered to start writing them for Medium, spying “a small opportunity to make each other laugh.” Their process basically consisted of bouncing ideas off each other until one of them laughed out loud. In its notes, Medium has hosted a t-shirt contest, published a Slack chat between developers, and written a false narrative about an engineer named Peter being hired and then fired for his work on the app.

“At first, we weren't that concerned with communicating real, tangible information,” Gueldner admits. For one important update that allowed Medium users to log in through their email and Facebook accounts, he and Fisher wrote a note full of puns based on songs by Kenny Loggins. It flopped—no one knew what improvements had actually been made.

Gill of Perform Group recently wrote a blog post urging developers to write better app release notes. In it, he advised authors to use bullet points, insert spaces between paragraphs, and include a clear and simple summary of the main changes at the top of the note. Some of his favorite notes come from Evernote, 1Password, and Tumblr.

Screenshot of an app release note by Yelp.

When a release note misses the mark, such as the Loggins one, Gueldner says he hears about it from Medium users. “Usually the place for immediate feedback is Twitter and the app stores," he says. “People will be like, ‘Enough with the stupid notes, tell me what's in this.’” 

Now, Gueldner tries to scale back the humor and provide more information when Medium is planning a big release. Once, he even published slightly modified code from the app update itself in the release notes. MacNeil takes a similar approach at Transit, reigning in his creativity slightly when a significant change has been made to the app.

It’s impossible to please everyone, though. A 2015 TechCrunch story titled “App Release Notes Are Getting Stupid” railed against bland updates as well as attempts at “performance art,” such as the time Medium rendered an ASCII portrait of a bug with the word “FIXES” in its notes.

An app release note from Medium.

Some critics of this peculiar genre like to claim that no one reads app release notes, anyway, especially since users can now enable automatic app updates. But one of MacNeil’s notes made it to the front page of reddit. On Twitter, Transit users have requested photos of him, called for him to get a raise, and pleaded with him to “never stop” writing the notes.

At Medium, Gueldner often looks to pop culture for inspiration—it could come from a Christmas carol, a political debate, or a movie. His creativity occasionally falls short, especially since he has been writing notes for almost three years. “I forget a lot of them now,” he says. “That comes up a lot, too. It's like, ‘Let's do Jurassic Park.’ And someone's like, ‘We've already done that.’”

For Gueldner and MacNeil, the challenge is personal as well as professional. “I would say the writers who write release notes—we don't really know each other,” MacNeil says. “But there’s absolutely a rivalry between us.”

MacNeil’s notes have given rise to Twitter spats between Transit, Pocket Casts, and Medium. He has also guest starred in the release notes of other apps, including Medium

For those looking to make a name for themselves in release writing, he has few words of advice. “I would say be pretty open minded, maybe have a beer before you write them,” he says. “There's no real rules.”

An abridged version of this post appears in the January 2018 print issue as “The Art of Release Notes.”

This article is for IEEE members only. Join IEEE to access our full archive.

Join the world’s largest professional organization devoted to engineering and applied sciences and get access to all of Spectrum’s articles, podcasts, and special reports. Learn more →

If you're already an IEEE member, please sign in to continue reading.

Membership includes:

  • Get unlimited access to IEEE Spectrum content
  • Follow your favorite topics to create a personalized feed of IEEE Spectrum content
  • Save Spectrum articles to read later
  • Network with other technology professionals
  • Establish a professional profile
  • Create a group to share and collaborate on projects
  • Discover IEEE events and activities
  • Join and participate in discussions