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

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.

posted almost 7 years ago

CC BY-SA 4.0

Monica Cellio‭ staff

2514 reputation 51 268 361 110

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.

posted almost 7 years ago

CC BY-SA 4.0

Secespitus‭

560 reputation 9 193 105 11

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.

posted almost 7 years ago

CC BY-SA 4.0

Mark Baker‭

4381 reputation 12 1104 745 58