Home Style guides Release Notes convention

Release Notes convention

General

When writing release notes, you should stick to common style and format for all company products.

The main quality standard for release notes: a client can easily understand what was updated and why. That is why you should try to avoid using general phrases such as “minor UI improvements”.

All the information required for release notes should be requested from Product owner.

Process

  1. A Technical writer starts writing Release notes after receiving a task for release documentation preparation.

  2. A draft for release notes should be written in Google document according to the template (refer to TBD).

Important

The link to the release notes draft is permanent. Do not create new Google documents every time you write release notes. Instead, use the ones listed at the end of this article.

  1. To avoid any misunderstandings, add “IN PROGRESS” at the very beginning of your Goggle document when working on the release notes.

  2. For each point of your release notes, add a link to the corresponding Jira task.

  3. The link to the release notes should be added to the Jira task for release.

  4. Release notes must be approved by:

  • Technical writer responsible for the review of the project

  • Lead technical writer

  • Product owner. If the release notes were significantly changed after Product owner review, release notes should be approved by Lead technical writer once again.

Template

Release notes draft should contain the following main sections:

  • Document name — the release date in the month date, year format, for example: November 10, 2022.

  • New Features — new functions and features. Every item should contain heading — a feature name or short description — and a detailed feature description specifying a feature location and purpose. Inner processes should not be described.

  • Improvements — enhancements of the existing functions. Each point should contain a detailed description of the improvement. Inner processes should not be described.

  • Bug Fixes — bug corrections. Do not describe bugs that appeared during regression testing and bugs that clients should not be aware of.

  • Release Message — a message that a bot will send to the project release channel in Slack. The message should contain NO MORE than 2-3 main points from the New Features and Improvements sections. Bug fixes must not be mentioned.

One or more sections can be absent (for example, if the release doesn’t have new features or bug fixes).

Upon Product owner and Lead Technical Writer approval you can add another sections, for example: Node Updates for B2BinPay. But the general structure of release notes should be preserved. Sections must not be renamed. Release notes format can be changed only upon Lead Technical Writer approval.

Release notes template

Tone&Voice

  • Use Present Perfect Tense.

  • Avoid first person form.

  • Avoid such words as problem, bug. Instead use the word issue.

to be continued…

Projects

Links to release notes drafts by projects:

#onboarding #tools