: 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 --

Vote Up Vote Down

Release notes should be written in the same voice as the User's Guide, online Help, and other documentation -- if they have the same audience -- because all documentation content (more than "voice") is based on audience needs, comprehension level, and purpose.

When I wrote release notes for Citrix Metaframe software, the notes had content, depth of detail, language and terminology that was appropriate for network administrators, because they were the audience. When I wrote "Read Me" files for Mac graphics software, I used language, details, and tone that was appropriate for end-uses and administrators (from a one-person graphic design shop to Boeing engineers) because that's who was going to read them.

"Technical" does not have to be dense, flat, and passive. Precision and clarity do not clash with simple and understandable; they are the same. User-friendly doesn't have to be folksy or informal.

I think the real answer is, don't be afraid to use the word "you" -- talk to the reader -- even in technical release notes. Just be sure you know who "you" is.

(0)

Vote Up Vote Down

It depends on the type of software you're delivering and your audience.

I've spend more then 10 years in embedded development and wrote a lot of release notes. In my company, we created the release notes for a new software release directly from the ticket tool. So the content looked like this:

Product Name

V1.2.3.4

123 - Adjusted IP frame length
124 - Removed redundant CRC checks

V1.2.3.5

125 - Reversed neutron flow polarity

and so on.

My intended audience were other developers, who also knew the technical details and weren't impressed by marketing blabla.

If you're audience is more on the marketing side, leave the release note 'design' to the marketing and only provide the data. They're mostly better in writing non technical sounding documents. We had a separate marketing dept. for those documents.

(0)

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)

Vote Up Vote Down

I agree with Mark's points about the distinction becoming less important in the current model of how your audience finds your content. Secespitus alludes to the importance of not annoying your technical audience, which I think is also a good thing to keep in mind.

I would take Mark's approach of not making a distinction in voice, as well as making sure that new users who stumble on the RNs when they search find enough contextual information about the product. To avoid annoying your existing users with introductory information that may be perceived as "fluff," consider breaking that out into an intro topic. Experienced users can skim right over it to see what changed in the last release, while new (or prospective) users get the context they need to better understand the rest of the content.

(0)

Vote Up Vote Down

In my opinion Release Notes should be written in a technical style, focused on the technical implications of the most recent changes. This makes them sort of a mix between the two worlds - you want to target decision makers and technical people and tell them what has changed when compared to the older version of the software, emphasizing what the problems are that may arise from these changes or what the problems are that these changes fix.

You don't want to sell the newest features and the whole product to the decision makers - they have already bought the product and want to know whether changing to the new version will cost them too much or if the fixes will offset the update costs.

You also don't want to sell the product to the technical people - they want to know what of their daily work will change by using the new version.

But you want to make it easy and fast to understand for everyone familiar with the old version of the software.

(0)

Vote Up Vote Down

Write for the audience, using whatever voice will best help them understand the meaning and significance of the release notes.

If there's more than one audience (e.g. end users and API users), write for them separately.

(0)