I confess, I’m a release notes reader, and I’ve read some overwrought release notes lately. When you use them like an installation guide, a features list, or a list of software conflicts, you’ve got it wrong.
The purpose of release notes is simple:
Release notes explain what changed with this version of your software. Period.
I hope this article will help you write release notes with clarity and brevity.
Title format for release notes
The title for your document should include specific information:
- Name of product
- Version number
For example, if your product is RubberDucky and this release is version 3.3.5, the title for your release notes document should be RubberDucky 3.3.5 Release Notes.
Make the title big and bold at the top of the page. Refer to it in links exactly as the title reads.
Consider following the title with these bits of information.
- One sentence overview of the product
- Date of the release
- System requirements
- Note changes, like “Discontinued support for Windows XP.”
- Link to installation instructions
- Link to a user manual
- Link to a release notes archive
Other sections in release notes
Break the release notes document up into sections, each with its own heading. Here are some sections to consider.
- Additions
- Removals
- Changes
- Fixes
Keep the actual descriptions brief. Release notes are often little more than a bullet list of updates, and that’s fine. If there are a series of small technical changes, try to describe them as a theme. For instance, “Improvements to the communication between the software and our servers.”
However, if there is an update that is important for users to understand, do not sacrifice clarity for brevity. Write enough of a description to explain the feature, but no more than necessary.
How do you know if an explanation is too short or hard to understand? Ask someone who is familiar with the software but doesn’t really know about the release to read the explanation and explain it to you in his or her own words.
What about personality?
Release notes should be easily scannable, and inserting witticisms should be avoided. However, if the company is proud of some feature, it doesn’t hurt to brag about it, so long as it is brief.
Here’s a nice example from TextWrangler 3.0 Release Notes.
What about posting existing, known defects?
This question quickly becomes a philosophical one. In my opinion, a company should be transparent about known defects with their software and earnestly try to fix those problems. You can see this type of behavior with some open source projects in that they have a public defect tracking system. The bugs are out there for the world to see. With enough of a user-base, defects with your software will probably become known eventually anyway.
However, I do understand that in some cases advertising known-defects is a security and stability liability and just shouldn’t be done. My preference is that that sort of decision is made on a defect-by-defect basis, and not as a corporate blanket statement.
Regardless, known defects or incompatibilities do not belong in your release notes document. You could, however, link to a list of them in your release notes.
Organizing archival release notes
What do you do with all those release notes from prior versions of your software? Archive them on your website so you and your customers can get to them.
One page, all release notes
If your release notes are brief, you might want to include each version on a single page. The most recent release notes should be at the top of the page. Fetch Softworks currently takes this single page for all notes approach.
One page of release notes per version
For the sake of clarity, I would prefer to have release notes for a specific version on that single page, with a release notes archive page that links to every version. BareBones Software takes this index of release notes approach.
Some companies keep a current release notes page up-to-date so they don’t have to continue updating links. Again, BareBones follows this approach: http://barebones.com/support/bbedit/current_notes.html
Do you have good (or bad) examples of release notes?
Not having seen any “best practice” document for release notes, I wrote this article. Do you agree? Disagree?
If you have examples of great, or really awful, release notes, please comment with the web addresses so we can all see them. Thanks.
20 responses to “How to write release notes”
Great post!
our primary use of “release notes” is from Project Management to Business, Upper Management and Customer Support. They are MUCH more verbose than you suggest in this article.
The primary audience that needs those notes is Customer Support and typically, they still need some more detailed info on what changes/ updates/ feature removals have occurred.
Good topic and I’d like to see more in the future.
thanks for posting.
Thanks Elianna. Good point. I think of the release notes you describe as a certain breed of release notes for internal use. There may be details that you would share inside a company that you would not share to external audiences, perhaps because the information is sensitive or it might only make sense to people in the company already.
Good article, thanks. Following link no longer works:
http://bbedit.com/support/textwrangler/notes_tw30.html
Hi, Davin,
Release notes are required when we send the Requirement document to client?
What is different between Release note and Release notes?
@Brian Thanks for the broken link note. I tracked down where that page moved to and fixed the link.
@Latha Elianna may have commented about about a similar type of release notes. This article is really about release notes made to describe a software release to the users of the software. Since you mention a requirements document, I wonder if you are talking about a document describing release planning notes as used in Agile (like Scrum) development, which would provide a list of user stories (features) that make up a future product release? That’s a very different topic.
Typically who should write the release notes for the software? A member from the development team or the tester who tests the release..???
A colleague insisted on including details about the next release of the product under the heading, ‘What to look forward to’ in the release note. I have not seen many instances of Release Notes with that format. I think that mentioning the next release details may increase customer expectations and if the release plans and features list change, it would disappoint customers. Please let me know your thoughts on this.
I’d be keen to know other technical authors’ thoughts on the following:
Do you include the following headings: Dropped Features or Coming up Next?
Do you include a Caveats section? I’ve seen a blog recommending this, but isn’t it covered in the Known Issues type sections? If you do include it, what do you put in it?
Do you add a Changes to the Release Notes section? If so, what do you put in it?
I guess there is so much conflicting advice online, I’m wondering if there can be any consensus?
@Zeba Good question, but I don’t know. What about someone from marketing to write the release notes? I think before it is published the release notes should be reviewed by someone (e.g., dev, QA, a project manager/product owner) for accuracy.
@ Priti I agree with your stance on this one. Release notes are supposed to explain what is different with this specific release, not past or future releases. Foreshadowing features to be released soon can probably be done in some other way.
@Dawn Thanks for these questions! I agree, it seems like this type of document is still unclear. I hope others will chime in on your questions. Also, if you have a link to some other release notes that we can consider, would you post that? On “dropped features” I’d say that it is important to include, since that would be a change to this version of the software. Upcoming features perhaps isn’t appropriate though, since it doesn’t have to do with this release. Where might that go? A corporate blog post? The product page in a highlight teasing an upcoming release?
And, I’ve never even thought of a “Change to the Release Notes” section.
When creating release notes, would a hot fix need to be listed? I always thought hot fixes are made to address a specific customer situation.
Also, does software jargon need to be eliminated or explained in detail? The type of jargon I am referring to are terms users might encounter when using the software.
Hi , do you have a sample of release notes?
I write the release notes for a software company and they are quite long (100 pages before I took over the writing, and I’ve gotten them down to 30 pages). The product manager keeps asking me to include screenshots and procedures and I keep telling them that these kinds of things don’t belong in release notes, and that users should refer to the online help for information about using a new feature. Have you ever seen procedural information and screenshots in release notes?
@Diane Wow! 100 pages of release notes for a single release? Nice job at trimming them to 30. To your question, I have seen procedural information and screenshots in user guides/manuals and online support documentation, but not in release notes. It sounds like you and your product manager have different definitions of “release notes.”
Great article and nice tips. this helped me create an outline for a release notes template. However, is there no standard for documenting release notes in software quality documentation from ISO or CMMI?
I used to write my company’s release notes and now I manage the current writer. I do think you need a dedicated technical writer to create the release notes, not a member of another department such as marketing. Technical writing is a specialized field, prepared to create the most effective written communication. If a company can, they should invest in a dedicated writer.
I agree with most comments here in that release notes should be as brief as possible…while providing clear details. I don’t think one sentence statements will adequately inform your customers. Sending them to other documents for all details is not always received well. They often don’t have the time to navigate several different documents. However, release notes should not become a user manual in the sense that you include detailed instructions and screenshots.
If the upgrade is controlled by your company, then customers may not get every individual version, so in this case you may want to include all minor versions in a comprehensive release notes document so customers don’t miss prior features.
My view on adding ‘coming soon’ to release notes is that there can be a risk of customers not deploying the current release and waiting for the next. This is a problem if you are trying to move customers up the releases. It depends on your product though so obviously that risk has to be assessed in the context of the product you are releasing.
It can be very difficult to get users to use online help (or any help for that matter) – I think the statistics back this up? I therefore believe that including some basic instruction in the release notes on how to use a new feature is beneficial. You have a captive audience, hopefully you have their interest, why not have them engage with the product immediately rather than sending them elsewhere for instruction on how to use a new feature?
Nice post.
I have a question as i am new in documenting the release notes.
My Question is that:
I have a mobile banking release note of a company, for which i have to ask questions related to it with the BA (Business Analyst) then what kind of questions can be formulated so that i can ask them.
The Release note document provided includes content related to mobility banking release version, usage and compatibility and integration.
Please provide the suggestions.