New Technical Writer-Don’t Confuse Your Reader With Your Words
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.
New Technical Writer: Use The Persona To Create The Most Useful Section Of Your User Document
OVERVIEW
A good User Document includes sections on how to set up, use, and care for the product. However, to create a great User Document ,
the technical writer should use the Persona, generated in the analysis of the User/Reader, to create the topics for the most useful section of the User Document. This article describes this procedure.
THE MOST USEFUL SECTION OF A USER DOCUMENT
The most useful section of a User Document is the one that helps the User get what he/she wants/needs done right now!
Writing such a section might seem to be an impossibility. How do you know what the User needs to do now?
The only thing that you, as a writer, can do is to play the odds. That is, determine the topics that have the highest probability of being of interest to your User. And “of interest” means “getting what the User wants done, right now.”
We created Persona (an almost-real representation of your product’s User) in another article in the “New Technical Writer” series
(see the links in the “Resources” or “Author Information” section of this article). We can use the Persona to create a topic list for this section.
USING YOUR PERSONA
This step in using your Persona is missed by almost all User Documents that I have seen. Yet this step will result in a User Document that is most satisfying to your Reader. Here it is:
Imagine your Persona using your product. Now, what are the main things that your Persona will want to do with your product.
As an example we will use a photo editing program (Acme FotoPhixer, a hypothetical product from a hypothetical company) that comes bundled with a point and shoot digital camera. Our Persona is a typical user of such a camera.
Ask: What does that Persona want to do with Acme FotoPhixer?
The short answer is that they want to improve their photos. HOW can they improve their photos with Acme FotoPhixer? In OUR words (not the words of the User) we could tell them how to:
* Rotate
* Crop
* Red-eye removal
* Adjust brightness & contrast
* Removing unwanted items from the photo
* Focus/Blur
* Save
* Print
* Share
These names are what we, the photography experts might use. However, “crop” may be meaningless to our Persona. In fact, we could move crop into “Removing unwanted items from the photo.”
The “Focus/Blur” topic is interesting. If a photo is out of focus or blurred, there is really nothing that our software can do to improve it.
However our Reader does not know this, but still wants to do it. We should include topic with this text: “It is impossible to fix the focus or remove blurring in a photograph.
You might be able to improve this using the [Sharpen Effect] tool in FotoPhixer.” (The [] specifies a reference to the topic in the User Document.)
DON’T HIDE THIS SECTION
If your Reader cannot quickly find what he/she wants to do in your User Document, then the document has failed.
Since we created this section to answer the User’s pressing needs for the product, then we must make this section very accessible to the User — they have to be able to find it easily.
“Fixing (Improving) Your Picture” is a PERFECT, User-oriented title. That is the correct title for this section. Don’t bury this gold under titles such as: “Tutorial” or “Use FotoPhixer’s Tools.” These titles do not suggest answers to the User’s questions.
You should make this section very easy to find in the User Document. It’s the key section of the User Document. It has the information that most Readers want, most of the time (by your analysis). Place it prominently in the User Document.
SATISFYING THE READER IS EASIER THAN YOU THINK
Producing this section is easier than you think.
First, imagine that you were NOT going to include this section. Your User Document would still have to cover all of the features, tools, and user interactions for the product.
You need to do that to satisfy your boss. It’s also logical. If a feature is not described, then why is it in the product?
Thus you have created a topic list for a “classical” User Document.
Now we create our User-oriented section, “Fixing Your Picture.” Here are the steps:
1. List each of the topics for fixing a picture, using titles that the Reader will understand.
2. Provide a brief overview, perhaps with a picture showing before and after the use of this fixing method.
3. Then list the steps for that topic, and provide links to the documentation for the relevant tools for each step
Done!
Actually, I would recommend using what I call a “Visual Index,” which is described in the links in the “Resources” or “Author Information” section of this article.
Within Document Re-usability
We could call this organization method “within document re-usability.” Here the writing for a topic exists as an item in the “reference” section of the User Document.
By referring to that item when it is needed for performing a User-oriented task, we make the text do double duty. This results in reusability within the document.
HOW TO GET THE TIME TO WRITE THIS SECTION
Put less detailed effort into the documentation for the product’s features that will be rarely used. For example, FotoPhixer includes tools to make the image look like it’s made of stone, or produce 3D effects, etc. These are rarely used, and have a similar set of controls.
Instead of detailing the use of each of these rarely used features, write a global usage, describe the controls, encourage the User to experiment, and remind them of the un-do and cancel capabilities.
You can create the “most useful” section with the time you save by not thoroughly documenting these rarely-used items.
THE BOTTOM LINE
You can make your User Document much more effective if you think about your User/Reader and what he/she wants to do with the product. Use this information to create an easy to find section in your User Document that meets your Reader’s needs.
how to become a technical writer without experience,what does a technical writer do,technical writer job description,technical writer salary,technical writer resume,technical writer jobs
