Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

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

+0
−0

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?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/33225. It is licensed under CC BY-SA 3.0.

0 comment threads

3 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+0
−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. 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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »