Category Archives: technical writing

How to write release notes

Release notes, sometimes called a changelog, let customers know when something’s happened in or to a product that could affect them. Various groups of people are involved in creating the release notes. Sometimes it’s hard to know what to include in the release notes. Here are some thoughts from me, after writing release notes for different types of products over the last few years.

The most important function of release notes is to let customers know that something has changed in the product, particularly when that something may affect the way the customer uses the product. The change may be a new feature in the product, an entirely new product, a change to the way the product works, a change to the way the customer uses the product, the removal of a feature, or even the deprecation of the entire product.

Examples of release notes

Atlassian creates comprehensive release notes for the major releases of each product, with graphics to illustrate the major features. For example, take a look at the Confluence 6.0 release notes. The minor releases list the issues resolved.

The Canvas release notes are full of information, including graphics to illustrate the top updates.

Release notes at their most minimalist are often called a changelog. A good example is the page for the Google Maps Android API. For a major release, the team includes screenshots and a tutorial on the Google Maps APIs Blog as well as in the documentation.

Some products support a complex set of variations in platforms and languages, as you can see in the Debian release notes.

Chrome DevTools kick off their release notes with a video and plenty of graphics.

Who writes the release notes?

Often, a technical writer creates the release notes based on input from product managers, engineering teams, marketing advisers, and other stakeholders.

In other cases, a various teams write or contribute to the release notes. For example:

  • The engineering team may write the simpler release notes, such as minor releases (point releases) consisting of bug fixes.
  • Product managers or marketing managers create the content for major new features or product launches. This is particularly so if the organisation’s primary promotion channel is a blog. A case in point is the Google Maps APIs Blog, which I mentioned earlier in this post.
  • A developer relations team may write software samples that illustrate a new feature in an API, and a video illustrating the new capabilities.

Letting customers know about the release notes

It’s a good idea to ask how customers will discover your release notes. It’s unlikely they’ll come and check your site regularly, just to see if something’s happened.

Here are some of the ways you can let customers know that you’ve published new release notes:

  • Provide an RSS or Atom feed on your release notes. For example, the release notes page for the Google Maps JavaScript API provides an Atom feed, updated each time the release notes are updated.
  • Write a blog post about major updates and other happenings that your customers need to know about.
  • Offer email subscriptions for your release notes and other product news.
  • Set up social media accounts for your organisation, and announce product news via those accounts. This tactic is useful if you know where your customers are likely to see the news. Examples are Twitter, Facebook, Reddit, Instagram, and more. For an example of indepth use of a particular platform, take a look at my post on using Twitter as medium for release notes.

An important point is to make sure there are links to the technical documentation from the release notes, blog, Twitter, and so on. The links help customers find the information they need after reading an overview of the new features/products. The links also boost the search engine optimisation (SEO) of the documentation, and let the customers know the docs exist as a good source of information.

What to include in the release notes

New features and products. Let people know about new features that enhance their use of the product. Provide an information-rich summary of what the feature means to the user, and how they can start using it. An illustration is good idea. Depending on the product, the illustration could be a screenshot, a photograph or video, a diagram, or a code sample. Also include a link to the documentation where people can find more information. If the feature was requested by customers and the feature request is publicly visible, link to it so people can see you’re listening to their requests.

Bug fixes. Include a list of the issues fixed in this release. Link to the documentation for further information where relevant. If the bug report is publicly visible, link to it so people can see you’re responding to their reports of problems.

Upgrade guide. Note any steps people need to take when moving from the older release to the newer release of the product. In some cases, there may be significant steps required. The nature of those steps depends on the type of product. For example, if the product is an API, the developers using the API may need to change their code. If the product is a software application, the system administrators may need to adjust configurations and update other applications that interface with or integrate into the updated application.

Deprecations and turn downs. Highlight any product and feature deprecations, and let people know when a product is turned down for good. A deprecation is a notice to customers that a feature or product is no longer recommended for use, and will or may be taken down at some point in the future. If there’s an alternative product or feature, let customers know where to find information about it. If possible, provide a migration guide telling people how to move from the deprecated feature to the new feature.

Other notes. Put yourself in the shoes of the user, and add the information you’d find useful. These notes may come from UX testing of the new feature, internal testing of the upgrade process, knowledge of customers’ procedures from the technical support engineers, or other sources.

Is a template useful for the release notes?

You could consider creating a template, to ensure that each update to the release notes follows a common pattern. Often though, the previous set of release notes is a good enough guide.

A template may also be a good idea for collecting information from stakeholders, but beware the content bloat that happens when people feel they need to supply words to fill a gap. Release notes should be lean and information rich.

More?

That’s about all I can come up with for now. Do you have any thoughts?

Advertisements

Publishing a paperback on Kindle Direct Publishing

The printed copy of my book has arrived! That’s a good reason to talk about publishing a paperback via Amazon’s Kindle Direct Publishing.

First, the long-awaited arrival of a printed copy of my book, A Word If You Please. I published the book on Amazon.com in Kindle and paperback formats. Being all the way down here in Australia, it was a couple of weeks before my hard copy arrived. And now, here it is:

  

It’s about an action hero, Trilby Trench, who also happens to be a technical writer. Does her way with words bring the danger to her or does it save her from further troubles? Only Trilby can tell you that.

Publishing a paperback on KDP

It’s been a while since I last ventured into the online tools provided by Kindle Direct Publishing. I’ve previously published two novels in Kindle format.

It was a very pleasant surprise that you can now create and publish a paperback version of your book. When I last published via Kindle Direct Publishing, only the Kindle format was available. The cost model for the paperback format is print on demand: You pay Amazon a fee for each copy that someone buys.

I loved the online cover designer. You can choose your design from a range of templates. There are different templates for Kindle ebook and paperback. Upload your image, customise the colours and fonts, and submit the design.

Only one thing didn’t work quite as expected. When you publish both a Kindle version and a paperback version of the same book, they start off as separate books on Amazon.com. It’s a good idea to get them linked, so people looking at the book online can see that both formats are available. The linking is supposed to happen automatically, based on identical title, author, and some other metadata. The auto-linkage didn’t happen for me, so I contacted the Kindle Direct Publishing help desk. They replied to my request within a few hours, and the update came through within 24 hours. Excellent service!

It’s worth spending some time reading the Kindle Direct Publishing documentation, to figure out how to upload and format your content. I decided to use straight HTML for the paperback version of my book. If you go that route, you may find this article useful: How to make an Amazon Kindle book using HTML and CSS. The author of that blog post has recently posted a disclaimer saying the post is out of date. Even so, I found the overview useful, and the downloadable set of sample files too.

Trilby Trench book now Kindle and paperback

The first book of my new Trilby Trench series is now available on Amazon.com as a Kindle ebook and in paperback form. Trilby Trench is an action hero who also happens to be a technical writer. She’s deft with words, analytic in thought, and skilled in everything that she’s written about. That covers a lot of ground. Things happen to Trilby, and she happens right back at them.

The book title is A Word If You Please. You can get it here:

I first published A Word If You Please in serial form, chapter by chapter, on the Trilby Trench site. Last week I went through the very interesting process of publishing the book with Kindle Direct Publishing, both as a Kindle book and in paperback.

If you order quickly, you just may see the paperback before I do. 🙂 I’ve ordered one, but it hasn’t arrived yet. It has to make its way from the US all the way to Australia. So I have no idea what it looks like in real life, or what it feels like to hold.

Review, anyone?

If you’ve read the book and are happy to put a review on Amazon, that’d be awesome!

What’s exercising your brain at the moment?

What are you thinking about at the moment? My recent musings are on the usefulness of technical communication skills to other people. By that I mean that people other than technical writers would benefit from learning core technical communication skills.

For example, organising information into chunks is a useful skill for all sorts of situations, including:

  • Compiling your resumé.
  • Writing an executive overview of your project.
  • Asking people to take action on something, based on your email message or a post to a social group.

Clarity and direct language are useful in all the above situations, and also in the following:

  • Putting your point of view in a fast-moving debate, or even in an argument at a dinner table. 😉
  • Communicating with people who speak your language at only a basic or intermediate level.

Short sentences and indeed short docs are useful when:

  • You or your readers are in a hurry. I guess that includes most situations these days!
  • Your words need to fit into a small space, such as a poster on a door, or a book review, or a Facebook page.

And so on.

Do you have any rambling thoughts to share, tech comm wise? (I’m enjoying the ambiguity of the last part of the previous sentence.)

STC Summit 2017 wrapup

This week I attended STC Summit 2017, the annual conference of the Society for Technical Communication. I’ve written summaries of the sessions I attended. This post is a wrapup of the conference as a whole, with links to my session summaries.

A huge thanks to the STC Summit committee, who’ve put together a fantastic conference this year. It’s been a few years since I was last able to attend a Summit (the last time was in 2014) and it was an absolute pleasure to be here again. I’ve met many friends, made new acquaintances, and learned what people are doing in tech comm.

There were approximately 600 attendees at STC Summit this year. The venue was the Gaylord National Resort in National Harbor, MD, close to Washington, DC. The conference theme was:

Gain the Edge to Get Results

Session summaries

There were approximately 85 sessions, with 5 to 8 sessions running concurrently in each time slot, over the course of 2 and a half days.

I wrote notes on most of the sessions I attended:

Other blogs

Kevin Cuddihy has posted session summaries on the STC Notebook. For example, here’s the post for Tuesday morning, which includes a writeup of my session. Thanks Kevin!

Here’s a good summary of the STC Summit from STC San Diego.

Social event: dine around

On Monday evening we gathered in groups and went to a few of the restaurants in the area. I chose Rosa Mexicana, where the food was good, the decor lovely, and the company outstanding.

The venue and surrounds

For a touch of local colour, take a look at my bookmark’s latest blog post about Georgetown, Washington, DC.

Here’s a view from inside the atrium of the Gaylord National Resort:

A view from the gardens:

The Potomac River at sunset, just a block away from the hotel:

It’s a wrap!

I’ve loved meeting everyone and attending all those interesting, entertaining sessions. Thanks so much to all the organisers, speakers, and attendees!

%d bloggers like this: