Skip to main content

Legal

Featured

Questions? We are here to help
Contact us

Tax & Accounting

Featured

Questions? We are here to help
Contact us

Trade & Supply

Featured

Questions? We are here to help
Contact us

Risk & Fraud

News & Media

Books

Developers

Content guidelines for Help and Support

Release notes

Consistency

We have 1 consistent template for product release notes that are easy to consume by customers. The template can be omnichannel. It can work whether it's delivered in Help and Support, email, PDF, Pendo, etc.

TL;DR (too long, didn't read)

Start with a summary for the people with no time but go into the details later.

Plain language

Write your release notes like you are explaining them to a customer, not your colleague.
  • Lead with the date
     - customers resonate more with a date than a release version. So title it like that.
  • Focus on the value to the customer
     - How does this release help them? Additionally, explaining the before and after helps them visualize the differences.

Keep them short

Don't turn release notes into a novel.
  • Include relative links
     - if you've got a new feature, your release notes should contain a high level summary of what it can do and where to find it. If they need more info like a step-by-step guide or video, send us a content request! We will make or update articles for this content. We can assume (and hope!) that customers want to use this feature over and over again, so they'll need access to this information outside of the release notes. Make sure to include the hyperlink in the release note.

Basic formatting

  • Bullets
     - break it down. People don't want paragraphs, they want summaries. You can use bulleted lists, or numbered lists, and one sub-level list. But no more than one sub-level.
    • If you are using lists in MS Word, make sure they are properly formatted using the toolbar (instead of just adding a dash (-). The import when you publish them to Help & Support will not recognize them as a list if you don't properly format them as one.
  • Sections
     - break down your release into new stuff you want to promote, things you've improved, and things you've fixed. New stuff should always come first.
  • Space
     - Make it easier for users to see the main points and not a wall of text.

Accessibility

Help and Support is required to be in compliance with WCAG Version 2.0, Level AA. It doesn't matter if a product is or isn't in scope; if the content lives on Help and Support we must comply. Visit our Accessibility page for more details.

Tables

Sometimes data is easier to consume in a table. However you should use them sparingly.
  • Pause and consider if a table is really the best format. Are there only 2 columns in the table? If so, can this be a list instead?
  • Every table needs a header.
  • Every cell needs data.
  • Don't use line breaks.
  • Make sure each piece of data has its own cell.
  • Review the full list of requirements on the WCAG website.

Images

Images are also a valuable thing to include in content, especially for new features. But we need to make sure the image is actually providing value to the reader.
  • Make sure the image is high quality (not pixelated) and does not have sensitive information in it.
  • Make sure it adds value to the release note, and what the image is conveying is also written out in the release note.
  • Every image needs Alt Text.
  • Review the WCAG website for more details.

This article applies to: