273
edits
Release Management/Release Notes: Difference between revisions
Added a Style Guide
No edit summary |
(Added a Style Guide) |
||
| Line 112: | Line 112: | ||
* Put a link to the reference release notes for the major version e.g.: Reference link to [https://www.mozilla.org/firefox/102.0/releasenotes/ 102.0 release notes]. | * Put a link to the reference release notes for the major version e.g.: Reference link to [https://www.mozilla.org/firefox/102.0/releasenotes/ 102.0 release notes]. | ||
=== | == Style Guide == | ||
* All URLs in notes should be de-localized. Typically this means removing the 'en-US/' portion of the URL. | Readers need to know what features are introduced/changed, the technical meaning of the feature, and the impact the feature will have on users. | ||
* A note that applies to both Desktop and Android should be written once and associated with both releases. | |||
* Don't link to bugs in the | * Aim to write in plain language: | ||
** Avoid using technical language. We should aim to make it easy for the reader to understand. Some technical terms may be necessary depending on the release note. | |||
** Avoid using colloquialisms or idioms. These can be confusing for readers depending on their region or their native language. | |||
** Avoid using abbreviations. For example, "pref" should be "preference". | |||
* For new or changed features focus on how it affects the user’s experience of Firefox, not what the software itself is doing. | |||
** Example: To prevent session loss for inexperienced macOS users, Firefox now requests the user’s permission to install itself if it is being run from a mounted .dmg file. This request is only made the first time Firefox is run on a user’s computer. | |||
** This could be written as To prevent session loss for macOS users who are running Firefox from a mounted .dmg file, they’ll now be prompted to finish installation. This permission prompt only appears the first time these users run Firefox on their computer. | |||
* For bugs focus on how the user was impacted. Start the release note with a verb in the past tense, for example Fixed, Added, Removed. | |||
* For known issues focus on how the user is impacted. If a workaround exists ensure to use clear instructions on how to leverage the workaround. | |||
* All URLs in release notes should be de-localized. Typically this means removing the 'en-US/' portion of the URL. | |||
* A release note that applies to both Desktop and Android should be written once and associated with both releases. | |||
* Don't link to bugs in the finalized release notes. | |||
** NOTE: Include links to bugs in dot release notes. | |||
* Group items that belong to a category together. For example, items with WebRTC can be grouped together. | * Group items that belong to a category together. For example, items with WebRTC can be grouped together. | ||
* Use full stops at the end of every note. The MDN [https://developer.mozilla.org/docs/MDN/Writing_guidelines/Writing_style_guide#writing_style Writing Style] is a good reference to follow for capitalization, contractions, numbers and numerals, pluralization, apostrophes and quotation marks, commas, hyphens, and spelling. | |||
== Nucleus: our publishing tool == | == Nucleus: our publishing tool == | ||