New Technical Writer: Don't Confuse Your Reader With Your Words

Summary: OVERVIEW 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. SAME CONCEPT: SAME WORDS 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 ...

OVERVIEW 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. SAME CONCEPT: SAME WORDS 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'?" DIFFERENT CONCEPTS: DIFFERENT WORDS 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." QUIZ 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. WORDS YOUR READER DOESN'T KNOW 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. DON'T BE AMBIGUOUS 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. THE BOTTOM LINE 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.