Add general style guidance based on the Release Note Improvement Initiative, Working Group 1

supplementary_style_guide/style_guidelines/release-notes.adoc

@@ -1,10 +1,67 @@
 [[release-notes]]
 = Release notes
 
-[[release-notes-doc-texts]]
-== Release notes doc texts
+A release note explains specific product behavior, capability, or problem relevant to a product version. Release notes for a particular product version are collected in a document that is published when the new version is released.
 
-A _doc text_ is a short description of an engineering Bugzilla or Jira issue that is published in product Errata advisories and release notes. Engineering typically supplies draft content, which is a summary of the issue, then technical writers edit or rewrite the draft content in accordance with the _IBM Style_ guide. You can write doc texts in more than one way, depending on the issue type:
+[[style-advice-for-release-note-texts]]
+== Style advice for release note texts
+
+The normal stylistic guidelines for documentation from the _IBM Style_ guide and the _Red Hat supplementary style guide for product documentation_ apply also to release note texts, particularly the following:
+
+Be clear and concise:
+* Focus on the impact on the user, and omit any overly technical details.
+* Avoid complicated syntax, such as passive voice and modal verbs, and ambiguous language. For example, replace "Should XY happen" with "If XY happens".
+* Write easily readable text. Avoid using infinitive statements that are common in merge requests and changelogs, for example, "Remove deprecated support macros".
+
+Define unfamiliar terms:
+* When you first mention a utility, package, command, or similar item outside of a heading, define it. Do not assume that the customer is familiar with it.
+* Omit the definition in later occurrences. If the context is ambiguous, for example, when the release note text mentions both an `example` package and an `example` service, you can repeat the definition to add clarity.
+* Avoid definitions in headings, but you can use them to disambiguate different meanings of the same name.
+* Expand abbreviations in descriptions. Do not expand abbreviations in headings. For more information, see "Abbreviations" in the _IBM Style_ guide.
+
+Use correct capitalization:
+* Do not start a sentence with a word in lowercase. You can repeat a definition to avoid starting a sentence with a lowercase name. For more information, see "Capitalization" in the _IBM Style_ guide.
+
+Keep admonitions to a minimum:
+* Avoid placing multiple admonitions in a single note.
+* Do not begin a release note with an admonition.
+* For more information, see xref:admonitions[Admonitions].
+
+
+[[tenses-in-release-notes]]
+== Tenses in release notes
+
+Write the release notes from the perspective of just after the release, which is when most of the customers read release notes. The state before the update is in the past and the state after the update is in the present.
+
+* Use the _simple present tense_ as much as possible.
+* Do not use _future tenses_ (or "should" or "might") to describe the state after the update. You can use future tenses to refer to potential future releases.
+* Use the _simple past tense_ to describe the previous situation before the current update.
+* You can use the _present perfect tense_ to describe the current update. For example: 
+With this update, the X component has been removed from the Y package."
+* Follow the CCFR (Cause-Consequence-Fix-Result) tense logic in bug fixes.
+* Do not use "now" to refer to the state after the update. For more information, see the xref:now[now] glossary entry.
+
+[[headings-for-release-notes]]
+== Headings for release notes
+
+Introduce each release note with a heading that summarizes the release note. This practice helps customers to quickly determine if the release note is relevant to them.
+
+* The heading can, but does not need to be, a full sentence. Do not use a period at the end of the heading.
+* Use _sentence-style capitalization_, not _title case_. If necessary, headings can start with a lowercase in the case of a lowercase component name. For example: "`start` does not start the computer when `donotstop` is stopped".
+
+* Write headings that are informative and specific without being overly long or too short. Adhere to the following guidelines:
+** Keep the heading under 120 characters.
+** Follow the specifics for the release notes type.
+** Mention the component in a heading whenever it might not be obvious.
+** Be specific; do not over-generalize headings. For example, "Program no longer crashes" is too generic.
+
+* Do not expand abbreviations in headings. If you use an abbreviation in a heading, expand it on the first mention in the text below.
+* Avoid definitions in headings unless necessary for clarity. For example, use definitions to disambiguate different meanings of the same name: "The `journald` system role can tune the performance of the `journald` service".
+* Do not start the heading with a gerund. Use gerunds only for procedural content.
+
+== Release note categories
+
+You can write doc texts in more than one way, depending on the issue type:
 
 * Enhancement
 * Bug fix