Apple has asked developers to do better with release notes — and so we figured we’d write about our system, in case it’s helpful to other developers.
Collecting the Notes
For major releases, our product managers (PMs) use our bug tracker (OmniBugZapper) to make sure there’s a note for each bug fix, new feature, and behavior change.
During TestFlight, sometimes its easier to use SCM logs (for example: svn log -r <revision of last release notes edit>:HEAD | less) to capture work in progress.
This phase is critical: being able to know exactly what has changed in a given release needs to be easy.
Writing the Notes
We have a build phase that renders Markdown to HTML and also replaces some tokens, so that, for instance:
- new - **Tags** --- Contexts have been replaced with Tags.
…becomes…
Our PMs use TextMate and BBEdit, and we’ve done some customization to make editing these easier, as in this screen shot:
Editing the Notes
We have an internal editors mailing list that all the PMs and a few other people are on. Much of our written communication passes through this list — including this blog post! — since we all have an interest in making sure everything we publish matches our standards.
Editors don’t always have feedback. Sometimes it’s just a thumbs-up emoji. But, when they do, it might be a wording suggestion, a question about something not clear, or just pointing out a typo — but the point is that everything ends up better by going through this process.
(Yes, the downside of a process like this could be that everything ends up sounding like it was written by committee. We’ve avoided that, but not by any magic other than just everyone doing a good job.)
We use the Apple style guide and recommend that you do too. Many of us have internalized the common rules, but things come up from time to time where we have to refer to the guide.
Here’s an example of useful guidance from the guide:
future tense Whenever possible, use present, not future, tense. Don’t switch unnecessarily from present to future tense when present tense is sufficient to express a sequence of steps or events.
Publishing the Notes
Release notes are included with each app — for instance, on the Mac, choose Help > Release Notes to see the latest. They’re shown in a web view.
They’re also published on our website. See the OmniGraffle 7.8 release notes for a recent example. Our CMS knows how to turn the Markdown copy into the proper rendered HTML.
The App Store requires plain text, so we convert the rendered HTML to plain text. Links are turned into plain URLs.
We try to localize the App Store release notes for major and feature releases.
We also localize the introduction and postscript for minor releases, so that customers who don’t read English know that it’s just a minor release, and they can read the info about contacting us for help or leaving a review. (OmniFocus PM Dave Messent uses a shell script that takes the introduction and postscript in each of our ten languages, and makes a sandwich using the plain text version of the meat of the release notes.)
We use fastlane to upload all the metadata for each release to App Store Connect.
Upon release of an app — once it’s been approved by the App Store and, in the case of Mac apps, also uploaded to our website — then there may be a blog post and accompanying social media posts, and these often link to the release notes. Minor releases don’t necessarily get a blog post, but release notes are still published on the website.
