Release Notes: Best Practices with Salesforce and Dropbox Examples

This tutorial explains how to write, format, and publish release notes. It also shares best practices, guidelines and examples from Dropbox and Salesforce.

Release Notes Template - MS WordDownload a MS Word Release Notes template here.

What are release notes?

Release notes give you brief, high-level descriptions of new features and enhancements to existing features. It also provides get setup information, implementation tips to get started, and best practices.

Release Notes Structure and Format

  • Release Notes – identifies the product name, release date, and links to other documentation, for example, previous release notes, user guides, or Sys Admin guides.
  • Feedback – offers an email address or link to a Customer Support page where customers can ask questions, raise issues or seek clarification about items mentioned in the release note.
  • Prerequisites – identifies software, hardware, or patches that must be installed before using the product. This may also include third party software such as specific versions of .NET framework
  • New Features – these are also called enhancements and usually relate to change requests. They identify new functionality in the release and explain where it is located in the user interface, any settings that need to be turned on, or parameters that need to be configured.
  • Known Issues – this lists all the bugs, errors, and issues found in the software. These are identified with unique numbers for tracking purposes. Note that some issues, for example, if they relate to performance, may not include a solution but will offer recommendations on how to avoid this occurring.
  • Installing your product – if necessary explain how to install or deploy the software, especially if there are different steps for each install.

Release Notes introduction

Start by introducing the release notes.

Welcome to the release notes for [your product]. Read these release notes thoroughly before you install [your product], as they contain information you need to successfully install the software that the [your product] help documentation may not cover.

This release supports the deployment of the [list the different operating systems.]

See the [your product] Documentation Library for the complete documentation for this release.

Feedback

Explain how they can contact you if there is an error in the documentation or if they need clarification.

To leave feedback:

  1. Email [your feedback email address]
  2. Provide feedback on the usefulness of this guide by filling out the survey at [enter URL]

Prerequisites

Next, describe the prerequisites.

For [your product] deployment, [your product] requires the following components, regardless of the operating system being deployed.

To install [your product] on:

  • [enter the operating systems, for example, [your product] 8, [your product] 7, [your product] Vista, [your product] Server 2012] install or enable the following components on the computer on which you install [your product]:
  • Microsoft .NET Framework  3.5
  • Java
  • [your product] 8:
  • Microsoft .NET Framework  4.0 (which is included in the operating system)
  • [your product] PowerShell version 3.0 (which is included in the operating system)

New Features

Next, describe the new features. Identify where they are located in the user interface, how to access them, and any parameters that need to configured.

For example:

The [version] update of [the product] includes the following new features:

Support for federated single sign-out using the WS-Federation protocol.

Web applications that use ACS to enable single sign-on with identity providers using the WS-Federation protocol can now take advantage of single sign out capabilities.

The [version] update of [the product] includes the following new features:

  • The rules engine now supports a new type of rule that allows up to two input claims to be configured, instead of only one input claim.
  • Localization in eleven languages. The Management Portal login page for relying party applications now support localization in eleven written languages.
  • An “English (International)” option is also available that uses an alternate date format for setting and displaying effective/expiration dates for keys.
  • Improved logging for better diagnostics – Logging levels will show WARNING for messages that should be reviewed. All other messages are logged as INFO. Only important messages are shown with level as WARNING.
  • Improved localization consistency

Changes

Identifies changes in functionality, for example:

The following are notable behaviour changes in this release:

  • Encoding is now UTF-8 for all OAuth 2.0 responses
  • In X.X.x, the character encoding set for all HTTP responses from the OAuth 2.0 endpoint was US-ASCII.
  • In  X.X.x update, the character encoding of all HTTP responses is now set to UTF-8 to support extended character sets.

Known Issues

Next, describe the issues.

  • Issue: When creating a license, ownership rights must be granted explicitly.
  • Solution: Your application must explicitly add Owner rights to the license owner when creating a license. For more information, read [documentation link].
  • Issue: If an application calls ProtectWindow twice for the same window by using its handle, SDK X.x will return a failure.
  • Solution: For guidance on this, see [documentation link].

Where necessary, provide recommended settings, if appropriate. Identify where the issue occurs in the user interface, how to find it, and any parameters that need to configured to replicate the issue.

For example:

The following issue is not specific to any deployment method:

  • There is an error in the Documentation Library help file in the section, “Support for [your product] 8,” in the document What’s New in [your product].

The text in the section reads as follows:

“[your product] Server is only supported in lab environments, not in production environments.”

The text in the section should read:

“[your product] Server operating systems is fully supported for production environments.”

  • [your product] may crash if the operating system image used to perform the deployment does not have the optional components. This situation can occur in the following scenario:
  • Performing the deployment scenario, where [other product] is enabled on the existing operating system. In this situation, [the other product] is suspended in the existing operating system by [your product], but without the optional component in the new operating system image, [your product] is unable to boot from the disk on which [the other product] is suspended.

The workaround for this to deploy a custom operating system image that includes the component in the image.

  • 64-bit versions of [your product] are unable to deploy to computers with firmware X.X.x.
  • Removing [your product] roles or features may fail, because the role or feature being removed has other roles or features dependent on it. The workaround is to ensure that all dependent roles and features are uninstalled before uninstalling a role or feature.
  • [product] does not include security templates. This means that there are no policy object packs.
  • When installing [your product] 10 using Setup.exe, two error dialog boxes are displayed. The dialog boxes do not affect the deployment, but you must click OK in each of them before the deployment process will continue.
  • Deployments fail when you select a boot partition that is not on disk 0. This is expected behavior.

Installing [your product]

Next, explain how to install the product, patches, or hotfixes, for example:

Make sure you have a complete backup of your server before installing [your product] on a computer that has an existing installation of [your product].

The [your product] installation process removes any existing instances of [your product] or [your product] installed on the same computer. Existing deployment shares, distribution points, and databases are preserved during this process but must be upgraded when the installation is complete.

Support for Upgrading from Previous Versions

[your product] supports upgrading from the following versions of [your product]:

  • [your product] Update 1
  • [your product] Update 2

Note: Create a backup of the existing [your product] infrastructure before attempting an upgrade.

Discontinue support for [product] 1.0

Support for [legacy product] is discontinued in this release, including support for migrating from [legacy product] 1.0 to [legacy product] 2.0.

[product] received an update that contained the following changes:

  • The entityID published in the WS-Federation metadata emitted by ACS is now consistently lowercase
  • The “entityID” attribute in the WS-Federation metadata published by Access Control namespaces is now always lowercase.

Error Codes

Next, list all error codes with explanatory details, for example:

If a Sys Administrator attempted to access the portal, they would receive one of the following error codes:

  • 50000: There was an error issuing a token.
  • 60000: An error occurred while processing rules for relying party using issuer ‘uri:[your product]LiveID’
  • 60001: No output claims were generated during rules processing.

Example of Dropbox Release Notes

Of course, you don’t always need to provide such detailed information. This example from Dropbox shows how to provide informational type release notes.

This approach is fine is you only want to publish improvements or important fixes to end users, not developers who need to modify the internal settings.

  • Enhanced Lion integration
  • Fix Dropbox not starting on OS X sometimes
  • Fix inability to leave shared folder bug
  • Fix install failure in Windows 2000.
  • Improved performance through use of Python 2.7
  • Improved web login from client
  • OS X: Fix Dropbox not autostarting after updating.
  • OS X: Fix icon overlays getting out of the Dropbox folder.
  • OS X: Fix notifications not showing up in Snow Leopard and below.
  • Provide more help information in the extremely rare case that Dropbox cannot start on Windows
  • Security enhancements, an attacker will not be able to steal your computer’s account credentials just by copying configuration files to another machine.

Example of Salesforce Release Notes

Salesforce provide probably the best release notes I’ve seen online.

You can download them in PDF and HTML versions.

Updates Via Twitter

When you follow @salesforcedocs on Twitter, you’ll receive notices whenever we publish new documentation or make significant updates to existing documentation.

Feedback

They look for feedback and make it easy for you to contact them. Instead of email, you can contact them directly on Twitter. Here’s what they say

“We know how important our documentation is to your company’s success. We want to know what works for you and what doesn’t.

Feedback forms: As you’re working with our documentation—whether it’s in the Salesforce Help, release notes, or developer guides at Salesforce Developers—look for the feedback form and vote up or down. Add comments if you have them.”

Tweet us at @salesforcedocs and visit docs.releasenotes.salesforce.com/

On the Release Notes webpage, you can filter the status of release notes as follows:

  • Any Status
  • In Review (670)
  • Scheduled (80)
  • Release In Progress (0)
  • Fixed (192)
  • No Fix (58

You can also search by tag:

  • API (51)
  • Activities (30)
  • Analytics (90)
  • Apex (118)
  • AppExchange (39)
  • Authentication (13)
  • CTI (5)
  • Campaigns (7)
  • Change Set (20)
  • Change Sets (13)
  • Chatter (31)

Release Notes Format

The structure is as follows:

  • Issue: The import wizard fails with a generic error.
  • Date Last updated: Yesterday
  • Reference W-1219912
  • Reported By 416 users
  • Status: IN REVIEW
  • Summary: Some customers using the import wizard may encounter difficulty importing one or more files even though all of the data is correctly formatted and all required fields are present.
  • Reproduction steps: The user will typically receive an email that an error has occurred and to either try your import again or contact Salesforce. This is not always indicative of this issue, other problems like not providing data for required fields or trying to update or insert duplicate values to unique fields can also cause this.
  • Workaround: The following knowledge article details various workarounds that should be tried first: https://help.salesforce.com/apex/HTViewSolution?urlname=Import-Wizard-fails-with-generic-error-message&language=en_US

Finally, a very good example of putting release notes online, including a screenshot is here.

PS – you can download a MS Word Release Notes template here.

Want More Writing Tactics?

Over 127,000 readers rely on Klariti every month. Sign up now for Ivan’s fresh writing strategies, practical advice, and resources delivered to your inbox each week.