: Re: Should software product release notes be in marketing voice or technical voice? (software documentation) Typically, the voice of marketing content doesn't match the voice of technical content --

@Turnbaugh521

Vote Up Vote Down

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. 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, 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 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.

(0)

Login to post a comment!