How we write Launchpad announcements
Each month, we in the Launchpad team make a new release.
Over the past couple of years, we’ve learnt some of what works — and what doesn’t — when announcing our releases. I thought I’d share some of that here.
Style and content
- Relevant: announce only what is of interest to the majority of your readers and what they can use “out of the box”. Direct your most ardent readers to the relevant milestone page in your bug tracker’ for the full details. Consider direct communication with those groups who are affected by a specific change. Ignore things that help you, the developer, rather than the reader.
- Personal: “The user” is not an abstract: they’re the person reading your text. Speak directly to them and show them how each change affects them. Use examples.
- Easily understood: don’t assume too much of your reader. Give them enough background to understand the problem you’re describing and your solution.
- Well ordered: start with the exciting, most relevant, stuff. Assume your reader has a limited attention span because, y’know, they do.
- Enticing: your readers are lazy and promiscuous. Suck them in by trailing the highlights in your headline.
- Bad: ACME releases a RoadRunnerStop v1.2
- Better: RoadRunnerStop 1.2: now easier to catch your lunch
- Better: Catch more road runners with ACME RoadRunnerStop 1.2
- Benefit-led: tell your reader how you’ve fixed their life.
- Good: Save time uploading branches to Launchpad
- Not so good: Launchpad now supports Bazaar stacked branches
- Bad: Launchpad will no longer OOPS when you attempt to alter a conjoined slave bug-task
- Plain-speaking: your readers aren’t stupid but you should err towards commonly used words and shorter sentences with fewer clauses.
Launchpad release announcements have four parts, in order of importance:
- headline/subject line
- detail of each change
- supplemental information: where to find more detail, other announcements, etc.
Take a look at the Launchpad releases page for some examples of our past release announcements.