Author Archives: Sarah Maddox
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:
- 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.
That’s about all I can come up with for now. Do you have any thoughts?
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.
I’ve recently published a fiction book, first in serial form on my own website, then as an entire book on Amazon.com. Publishing the book in serial form, chapter by chapter, was an interesting experience. It was an experiment. I wanted to see the pros and cons from an author’s point of view and from a reader’s point of view.
The book is A Word If You Please, featuring Trilby Trench and a collection of friends and foes. Trilby Trench is a technical writer who likes a bit of action. As Trilby’s friends know, adventure stalks Trilby and she stalks it right back. The serialised book is online on the Trilby Trench site (free of charge). You can also download the book from Amazon.com as a Kindle ebook (USD $3.11) and a paperback (USD $6.99).
Why serialise a book?
I’d been wondering about publishing in serial form for a while. What would it be like for me as author and for the people reading my book?
For example, would publishing the book in serial form be a good way of getting feedback from readers? In my case, the answer is yes. More people have sent me comments about this book than about the other fiction books I’ve published. The comments come in on Facebook, the Trilby Trench site, and other social media.
For an author, publishing a book chapter by chapter can be a challenge. Once you’ve published a chapter, you can’t go back and change it. That’d be breaking an unwritten contract with your readers. Actually, it’s a written contract, kind of! So, if your plot goes awry or you forgot to include something in an earlier chapter, you have to work around that. Before publishing the first chapter, you need a very good plan for the entire book. I like to have it mostly written, though not necessarily polished and complete.
This way of publishing made me think a lot about my readers.
What do readers think of the experience? Some may find it fun to have to wait for the next instalment. The suspense may increase their interest in the book. Others may find it annoying to have a break artificially imposed on them, or may lose the thread of the story. Perhaps a serialised book would stick in people’s memories longer than if they’d read it all in one go. Perhaps some people simply wait until all the chapters are available!
Where to publish a book in serial form?
I took a look at a few options for where and how to publish the book online.
Wattpad is an online community for readers and writers. If you publish your work there, you have a ready audience and a medium that’s well designed to bring authors and readers together. I wasn’t too sure that the primary Wattpad audience was right for my book. The most popular genres there are science fiction, young adult, and fantasy, and my book doesn’t fit into those categories. Also, Wattpad keeps popping up requests to log in, even if you’re a reader and not an author. I think that’s a barrier to entry for readers.
I also like the look of Inkitt. It has a clean UI, and it focuses on readers rather than authors.
After careful consideration, I decided to publish the book on my own blog or site, so that I could have more control.
One option was to publish the book on this blog (ffeathers.wordpress.com, where you’re reading this post). One the one hand, the focus of this blog is fiction as well as technical writing, so it’d be a good place for the book. On the other hand, this blog is primarily a blog, whereas I wanted a site that focused on the book rather than the blog posts. So, I needed a different layout, and I didn’t want to mess with ffeathers.
After weighing up the options, I decided to create a new website for the book. In fact, the website is for the character, Trilby Trench, as I plan to publish more than one book with Trilby as hero. Hence the site name and URL, trilbytrench.com. The site runs on WordPress, hosted by Bluehost. I’m using the Author theme, with some CSS tweaks to change font sizes (the default size was too small) and colours.
What do you think about serialised fiction?
If you have any comments from your experience as a reader of serial fiction, either my book or others, I’m keen to know what you think. What are the pros and cons of reading serialised fiction? Comments from authors would be interesting too!
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:
- Amazon.com: Kindle ebook (USD $3.11) and paperback (USD $6.99)
- Online book on the Trilby Trench site (free of charge)
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.
If you’ve read the book and are happy to put a review on Amazon, that’d be awesome!
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.)