Purpose of release notes
Where relevant, release notes should answer the following questions about the product release or update.
- What has changed in this version?
- How does the change impact the user (including benefits)?
- Does the user need to do anything differently as a result of the change?
Writing guidelines
| Do | Don't |
|---|
| Use What's new marketing content if available to create a friendly overview of the release. | - |
| Use past tense to explain bugs, and present simple or present perfect tense for features. | Do not use future tense. |
| Provide a brief summary of each feature or fix. | Do not include the reason for a bug fix, examples, or your opinion. |
| Use titles consistently. Keep them concise, on a single line, and limited to a few essential words and key elements. | - |
| Add a link to other help materials for new features if relevant. | - |
| Use screenshots or videos to explain new features if relevant. Follow motion and animation accessibility guidelines when including video content or animated GIFs. | - |
| Include the year and update number in the release notes file name. | - |
| - | Do not include internal terminology or release codes. For example, release codes, environment, or Jira reference. |
| - | Do not use standalone function or parameter codes. For example, "Go to the GESXDC function." |
| Remove unnecessary words like available, finally, now, or previously.If there's a major change in workflow, limited use of now and no longer can help the user understand the impact of the change. | - |
