Re: upload/download terminology

Subject: Re: upload/download terminology
From: Chuck Martin <cm -at- writeforyou -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 09 Jun 2004 10:35:37 -0700

wswallow -at- nycap -dot- rr -dot- com wrote:

OK, question:

Which is more valuable to you and your customers?

1) Documentation that uses real industry terms and properly and eloquently defines them so everyone then understands what these terms mean and can apply them to your product and outside the contect of your deliverable.

2) Documentation that skirts around the use of real industry terms in order to convey information to a captive audience who can apply their knowledge from the documentation only to the deliverable.

I vote for #1. Why?

Well, I vote for #3: Documentation that is designed from an understanding of user goals. While that leans toward #1, it's also important to use the language, tha jargon, of users.Sometimes that means within-text mapping of user terms to "real" terms.

Your audience will be better off in the long run knowing the correct terminology. Should at some point they buy an additional product to use in their jobs that uses the same terminology, they can draw associations easily and not get confused. Otherwise they could look at "upload" in one document and "FromHandheld" in another, and perhaps "korlsomfgam" in another and puzzle over whether these are indeed the same or not. In that case, your skirting around the standard terminology just confused them, which is what you were trying to avoid, right?

Who are we to say how our audience will be "better off?" They are "better off" when they reach their goals, quickly, easily, and with a minumum of frustration. They are not using your product to learn correct industry terminology.

Also, if you are using custom terminology for standard terms, you now have "reverse education" happening, where you need to educate everyone working on YOUR team from this point forward on what these terms actually mean and refer to, and you have to make sure they are all being used consistently by everyone, thus potentially confusing YOUR team.

Somehow, I don't see the problem with that. If your product team doesn't know the vernacular of your users, you have a far, far deeper problem that choosing what terms to use.

And furthermore, you can create a section in your very first chapter to define these terms and other concepts that will be used throughout the documentation, and then you can reuse this section in every publication you produce.

A section that in all liklihood won't be read. User rarely *read* manuals, and almost never linearly front to back.

Of course you also have to consider audience members who DO know a thing or two... How will they react to seeing something they know and understand as "upload" being refered to as FromHandleld or korlsomfgam? Wouldn't you think that would be confusing for them, YOUR POWER USERS? These are the people who should be able to pick up the product and easily master it, and teach others to use it properly. You certainly do not want to confuse THEM!

You shoudl not be designing, either product or documentation, primarily for "power users." Nor should you primarily for beginners. Focus your efforts on perpetual intermediates, then add enhancements for outliers and corner cases when appropriate.

Teach them the right way, which is why I suggested you properly define the standard terminology and use it. Everyone wins.

You can assume your audience is "stupid", but you don't necessarily need to nurture that assumption. That itself, IMHO, is "stupid".

Assuming that your audience *wants* to learn all about your product, the way you think it should be used, and the way it should be communicated about, is programmer-like arrogance. (As is the belief that users are "stupid.") It's a shoddy way to treat the people who shell out their hard-earned money.

Besides, users are far from "stupid," they just don't know about your product. They are smart in their own domains--which is where their priorities lie, not in learning about what you're so passionate about.

We have the power and the capability to understand how users work, play, and communicate, and we should be the ones who bend to accommodate them, not vice versa.

Chuck Martin
User Assistance & Experience Engineer
twriter "at" sonic "dot" net

"I see in your eyes the same fear that would take the heart of me.
The day may come when the courage of Men fail, when we forsake our
friends and break all bonds of fellowship. But it is not this day!
This day, we fight!"
- Aragorn

"All you have to decide is what to do with the time that is given you."
- Gandalf


SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more!
From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: upload/download terminology
Next by Author: Re: How to set up a listserve?
Previous by Thread: re: upload/download terminology
Next by Thread: Re: upload/download terminology

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

Sponsored Ads