Should software product release notes be in marketing voice or technical voice? (software documentation)

Question

Typically, the voice of marketing content doesn't match the voice of technical content -- marketing is trying to persuade you that you need something; technical writing is generally instructing you how to use something. (I'm specifically talking about software.)

I have traditionally taken a techcomm approach to release notes -- describing new features and bug fixes in a straightforward manner, focused on the user. The marcomm folks often describe the features with a very different vocabulary. For most content, this distinction is clearer -- software documentation is techcomm; web sites, blogs, press releases are marcomm.

A case can be made for the release notes serving a marketing purpose in addition to a technical purpose -- reaching business decision makers in addition to technician-type users. How do you decide the appropriate voice for the release notes?

Answer 1

I think that there is a very strong case to be made that this distinction between marketing voice and tech comm voice should be avoided entirely. There are two main reasons for this:

1. In ancient times, when tech comm and marketing were delivered on paper, each came to the customer at a different time and through a different channel. Generally they were done with using marketing content before they even got an opportunity to see technical content. But the web has changed all that. Marketing and technical content are all available to the customer online. But since the user is finding this material largely by search, there is no telling if their search is going to land them on a technical or marketing document. A marked difference in style between the two is jarring for the customer.

2. There is a great deal of evidence to suggest that traditional ra ra marketing tone simply does not work any more. The web allows people to get information from so many sources that they don't have to subject themselves to blatant propaganda in order to get information on a product. Wise marketers have responded by moving to content marketing, which focuses on producing content that readers actually want, as a means of attracting them to your company's content and of building the reputation of your company as experts in the field. Good content marketing cannot have the old marketing ra ra tone or it simply won't get read. Tech comm, on the other hand, can no longer rely on the customer already having bought the product. Many customers are going to make their purchase decision based on the quality and availability of the documentation. You can't afford to neglect this aspect of how documentation is used. (Besides, once the company catches on that tech docs are generating leads, your stock in the corporation will raise considerably.)

Unfortunately, there are many impatient marketing people who have a hard time producing depth or substance, and many grumpy old time tech writers who have a hard time accepting that they have to write things that the general public will read while making a purchasing decision. But both these groups are living in the past. In the content marketing era, all content is marketing content, including (and sometimes especially) tech comm content. It is all one thing. It should all have the same tone.

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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.

Answer 6

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.

Answer 7

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.