Post History

Source: https://writers.stackexchange.com/a/33232
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Release notes should describe what changed _as seen by the users_. That doesn't necessarily mean "all the gory technical details", though; as with other technical writing, you want to tell the user what he needs to know (and maybe a little more), but you don't want to overwhelm him with unneeded details.

If there are larger themes in a release, you might also add a short introduction about them. Major releases sometimes use the release notes to highlight key new features, for example. These are less _functionally_ oriented and can be more of what you're thinking of as "marketing", but the best ones, in my experience, use a style similar to what you'd use in the overview of the technical documentation. Release notes aren't a sales vehicle.

As an example, see [these recent release notes for Firefox](https://www.mozilla.org/en-US/firefox/58.0/releasenotes/). They're for a major release (58.0) and start with a general paragraph. Then they get into the individual notes -- new behaviors, fixed bugs, etc. Each of _those_ is user-oriented, such as:

> New: Improvements to Firefox Screenshots:  
> - Copy and paste screenshots directly to your clipboard  
> - Firefox Screenshots now works in Private Browsing mode
> 
> Fixed: Fonts installed in non-standard directories will no longer appear blank for Linux users
> 
> Developer: Implemented the PerformanceNavigationTiming API

Firefox also has [release notes for developers](https://developer.mozilla.org/en-US/Firefox/Releases/58), which divide the notes by component and provide more detail (and more links). Developers are a different audience than end users; as with your other documentation, you have to calibrate the content to the audience.

If your release notes are digital (not on paper), then you can also link to related information. In the Firefox example, that one about the PerformanceNavigationTiming API is a link. My team's release notes sometimes link to specific topics in our documentation. The [release notes for Visual Studio Code](https://code.visualstudio.com/updates/v1_20) demonstrate this style. (Thanks to Bob for pointing out some examples in a comment.)

In a comment on the question, somebody raised release notes generated from code checkin comments. Such release notes are more of a change log because they show all the changes "as they fell". The kind of release notes that I'm talking about, and that I think you're asking about, are higher-level than that and call for some distillation.

Original score: 29