Re: Choosing and managing customer-facing terminology

Subject: Re: Choosing and managing customer-facing terminology
From: "MARK bAKER" <mbaker -at- analecta -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 21 Sep 2011 15:06:37 -0400

I'm curious about how writers choose terminology that will be exposed to
customers. In particular, I'm thinking about text that is highly visible
and informs the users' view of the product, like embedded assistance in
software documentation.

A few thoughts:

1. Use the terminology of the user community. Plain old English is the right choice if your audience are plain old folk. If your audience are specialists, they will have a specialist vocabulary, which you should use. (Resist the temptation to believe that specialist will understand plain old English just fine. Specialized vocabularies don't exist to confuse outsiders, but to enable more precise communication among insiders. Plain old English does not express distinctions that are important to specialist in their specialty. To translate the message to plain old English will be to obscure those distinctions, and that will usually lead to something getting broken or someone getting hurt.)

2. Use the same terminology as the product interface. You may have a much better name for the blue button than the one actually printed on it, but you will only confuse if you write "Start" and the button is labelled "Execute". By all means work with development before the release to improve the works that appear in the interface, but if you can't beat them, join them.

3. If you want to work for consistent and appropriate terminology, you can't just work with development. Effective terminology control has to come from product management and has to involve your marketing, sales, and field organizations (the people who actually talk to your customers every day). The place to start any initiative is with the product manager for your product.



Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Choosing and managing customer-facing terminology: From: Julian Cantella
Re: Choosing and managing customer-facing terminology: From: Gene Kim-Eng

Previous by Author: RE: Tech Writing in Kanban
Next by Author: RE: Name of Hardware Control?
Previous by Thread: Re: Choosing and managing customer-facing terminology
Next by Thread: I have a list of URLs, I need to print the pages

What this post helpful? Share it with friends and colleagues:

Sponsored Ads