New Technical Writer Dont Confuse Your Reader With Your Words


Stop confusing your Reader with the words you use. Your Reader is​ trying his/her best to​ understand how your product works without having to​ figure out your writing. Here are some writing guidelines to​ help you stop baffling your Reader.


User Documents are not meant to​ be entertaining. Do not try to​ be creative, especially by using synonyms for specific concepts in​ your product. When you talk about a​ topic use the exact same wording to​ describe (or name) the topic everywhere in​ your User Document.

For example, the "Same Concept: Same Words" guideline, says that if​ there is​ a​ control on your product called the "Activation Button," then everywhere you talk about that button use the term "Activation Button."

Don't be "creative" and use words like "Activation Control" or​ "Start Control" to​ refer to​ the "Activation Button." Using the different wordings forces your Reader to​ have to​ stop and think "Is this the same thing as​ 'Activation Button'?"


I bought something on the Internet that had a​ rebate available for it. When I ordered the product, I was given a​ "Tracking Number" to​ monitor the progress of​ my order. This is​ common for orders from large companies.

When I applied for the rebate, the rebate company used the same word, "Tracking Number," but this time it​ meant "their rebate tracking number." When their website asked for "tracking number" I entered the only one that I knew, the product ordering tracking number. I was wrong; the rebate number was a​ totally different thing.

The Rebate number is​ different from the order tracking number and should have a​ very different name from the order tracking number.

One might argue that "the rebate company is​ a​ separate company, and must handle rebates for all sorts of​ sellers." Sure, but they can use a​ very specific name for their rebate tracking number. They can call it​ the "Rebate Identification Number." That name would not be used by any selling company to​ track an​ order. The problem is​ solved. No User would confuse "Tracking Number" with "Rebate Identification Number."


Given the information in​ the previous two sections of​ this Article, wouldn't it​ be really silly if​ the rebate company originally called it​ the "Rebate Identification Number" and then unannounced switched to​ calling it​ the "Rebate ID"? Answer: Yes, it​ would be very silly. The change forces the Reader to​ have to​ ask, "Is this the same thing as​ the 'Rebate Identification Number'?"

It's not that your Reader is​ too stupid or​ lazy to​ figure out what you mean. It's that your Reader has better things to​ do than to​ decipher your writing.


Jargon is​ the shortcut language of​ any industry. Make sure that if​ you use jargon in​ your User Document, you explain what it​ means. if​ the writing project can afford the bit of​ time, I recommend that you include a​ glossary in​ your User Document. Define all the jargon, acronyms, and words that you might use in​ ways your Reader might not expect. a​ great example of​ the latter are "debit" and "credit." The common understanding of​ these words is​ exactly opposite to​ those in​ the accounting (banking) profession.

TIP: Be suspicious of​ any words your spelling checker identifies. Ask yourself two questions when your spelling checker identifies a​ misspelled word:

* Did I really spell that word incorrectly?

* if​ it's spelled correctly, am I certain that my Reader knows what the word (or acronym) means? if​ it's not in​ the spelling checker's dictionary it​ might not be in​ your Reader's vocabulary.


I have a​ notebook computer running MS Windows XP. if​ I am using the Media Player and I press the keys to​ hibernate the computer (put it​ into an​ energy-saving sleep state), something warns me that hibernating will lose my place in​ the video. it​ then asks: "Do you want to​ continue? Yes/No." Continue what?: Continue hibernating, or​ Continue watching the video? it​ would only take one or​ two more words to​ remove the ambiguity.


When you revise your writing, make sure that your Reader does not have to​ guess what a​ word might mean. if​ you mean the same thing as​ another concept, use the exact same name. if​ you mean something different, then use as​ different (unique) a​ name as​ you can. Define jargon, acronyms, and any unusually used words. Eliminate ambiguity.

Your reader is​ uncomfortable enough having to​ read your User Document, instead of​ using your product. Don't make things worse by using wording that makes your Reader have to​ work out its meaning.

Related Posts:

Powered by Blogger.