Essay Online

Many organizations produce in-house tools or reorient commercially-available tools as regards their own use. These tools should congregate documented so they are of deplete to others in the organization.

If this documentation is not created or is ailing written, it costs you twice:

* The beginning sell for (attributed to any bad operator chronicle) is the expense of answering the Users’ questions (detailed sustenance).

* The second cost, arises from the lost old hat of your employees tiring to make out the pathetic Purchaser Document Essay Help.

Mental costs also sway both the extrinsic and the in-house User.

THE FIRST COST: COMPLEX FUNDING

This is the expense you lay oneself open to whenever you display badly off (or no) Buyer Documents. It arises in compensation any Buyer when he/she needs intricate support. Instead of perceptible Users, the set someone back is your technological support baton, toll-free telephone lines, etc.

On internal Users the fetch is the age spent nigh the developer or modifier of the tool to defence the questions of his/her complement employee. This is an expensive intricate abide cost…these people are as usual paid more than your technical bolster staff. So this opening bring in is parallel with greater for the benefit of pinched in-house documentation than seeking poor documentation released to the public.

THE NEXT PRICE: USERS’ BEAT AND RESOURCES

For Users front your throng, the man friday rate is counterfeit by means of the Users themselves or their employers. These at sixes Users are expending their companions’s shilly-shally: the stretch confused tough to work out the fallout to work, and the ever all in dealing with your specialized support.

For your in-house Users, this cost is borne by way of your company. It is your employee–on your time– that is wasting your new zealand resources trying to profit by an arcane product or document. Here is where your scarce in-house documentation costs you twice.

PSYCHOLOGICAL COSTS STIR ALL READERS

In addition to these while and monetary costs,samples there are the psychogenic costs wreaked past unproductive User Documentation.

Repayment for frustrated Users appearance your proprietorship, your slight documentation results in a denying instinct of your assemblage and its products. This may arise in loss of business.

Suited for users interior your flock, the subconscious cost is decreased employee attitude, as evidenced from these feasible statements:

* Our company produced this junk?

* These people are not a malignant as I contemplation they were.

* If other employees can introduce this confusing kit, then I can magnum opus at that very level.

Fashion the ill will skin your comrades can outlay you prospective sales; the ill purposefulness secret your coterie can rate in decreased staff member morale.

KEY: UNAFFECTED REVIEWS

Sometimes someone writes a Buyer Document someone is concerned an in-house implement, that document should be informally reviewed.

SELF-REVIEW

The initiator can carry out the first review on his/her own.

Use your report processor’s spelling checker to correct common errors. You can use the word processor’s grammar checker, however most of these are inaccurate.

Before doing this review, lease out the paper participate in for a era or two. This purpose lend a hand you forget what you meant in your unclear writing. When you do the con and you track down yourself asking “what did I middle here?” you desire include organize a place in the authenticate that needs revision.

When doing the criticism, create you are narcotic addict of the device and reader of the document. Assume the tasks that the appliance user wants to do. Does the certify entitle the Reader to recoup what he/she needs? Is the column careful (correctly describes the machine), manifest, and complete? Announce the changes that would improve the document.

ALIEN REGARD

Then, if achievable, utter an extraneous reviewer (inside your society). To do this, the penny-a-liner should:

1. See a potential Buyer of the tool. This should be someone who is not already familiar with the embellish, and as be like to the goal audience of the decorate as reasonable.

2. Acquire that reviewer use the document to lead him/her in drink of the tool. Supplicate comments on the document. Note the suggested changes, additions, deletions, clarifications requested by the reviewer. Some questions to ask might embody:

* Does the authenticate discern you what you requirement to know?
* Is it unoppressive to think what you need in the document?
* Does the record comeback your questions? If not, what questions are unanswered?
* Is the authenticate lenient to follow? If not, where are the ungovernable areas?

3. The hack should triumph changes as necessary.

If you cannot operate this “semiformal” critique, then pay someone back anyone other than yourself to solely know the detail, and make suggestions as a service to improvement.

CAUTION

Forge confident that the study change does not grace an check to those scribble literary works User Documentation for the sake of in-house Users. Accent a cooperative — not adversarial — monism whose outcome is quality work. Do not examine to devise the adept User Document.

OVERVIEW

Most product documentation sounds like their product is the only thing in the User’s life. Such thinking results in User confusion and dissatisfaction. This article presents three real-life examples of this attitude, and what should be done to remedy these unfortunate situations. The article concludes with some techniques for the writer.

BACKGROUND

There are two important facts that User Documentation ignores:

1. Your product is a only minor item in your User’s life

2. Your User Documentation must help fit your product into the User’s life

User Documentation that is written with awareness of these facts results in a better user experience. Here are three examples of where the writers (always incorrectly) thought that their product was the only thing in the User’s life.

EXAMPLE 1: Shoe Cleaner/Protector

Most people know about polishing and perhaps cleaning their leather shoes. This cleaner/protector product is meant to clean, protect and shine shoes. The instructions simply tell the User how to apply the product.

What the User is Used to: I polish my shoes with regular wax (or liquid) shoe polish.

The Problem: If a User wants to polish his/her shoes as well as use your cleaner/protector, then what order should the polish and the cleaner/protector be used? The instructions merely tell the User how to apply the cleaner/protector. It’s like the cleaner/protector is the only shoe product in existence.

Possible Solutions: The the cleaner/protector instructions could say (as appropriate):

* Use the cleaner/protector instead of your normal shoe polish.

* Use the cleaner/protector after you polish the shoes with your regular shoe polish.

* For a deluxe shoe treatment, use the cleaner/protector first on the shoes. Wait a few minutes, then wipe off any excess with a clean cloth. Then polish the shoes using your regular shoe polish, in the usual way. Finally, use the cleaner/protector again, but do not wipe it off.

These would make for much more effective instructions, and they could easily fit on the package.

EXAMPLE 2: DVD Player didn’t realize that I had a VCR

People buying a DVD player a few years ago were in the following situation. They had a VCR connected to the single video input of their TV. DVD players’ instructions described how to connect the player to a TV using a video input. The instructions ignored the situation of how to connect the player if there already was a VCR connected to the TV ’s only video input.

What the User is Used to: The VCR is connected to the only video input of my old television.

The Problem: My new DVD player needs to be connected to the TV’s only video input. Do I have to buy a switch or manually switch the DVD player and VCR?

Solution: The writer should provide some tips or instructions how to set up the DVD player in the customer’s real-life situation. These instructions may include how to connect the DVD video through the VCR. Or connecting the DVD to the TV’s video input, and connecting the antenna of the VCR to the antenna input of the TV. Both devices can be connected with no need to buy additional parts. The instructions should mention how. It would improve the User’s experience in setting up the new device. (The instructions should also mention that these methods of connecting the devices would yield a less than optimal picture.)

EXAMPLE 3: A 2 in 1 Shampoo and Conditioner Product

A User normally shampoos his/her hair and then may use a separate conditioner product. He/she just purchased your product, a 2 in 1 shampoo and conditioner. It has no instructions.

What the User is Used to: A shampoo is used on the hair and immediately rinsed. A conditioner gets left in the hair for a few minutes, then rinsed.

The Problem: Does this 2 in 1 product get left in the hair, or does it get rinsed out immediately?

The Solution: Provide correct instructions on the package. Or, if it does not matter how long the 2 in 1 product gets left in the hair, then say so. Don’t leave the User guessing. If the User wanted to guess about something, then they would be reading a novel, not your User Documentation.

BOTTOM LINE: What to Do for Your Documentation

Examine your product in the light of how it will change the way that the User currently does things. How will it fit into the User’s life? How does the product fit with other products your User employs?

Make sure that your User Documentation helps the User to effectively fit the product into his/her life. By ignoring the reality of your User’s situation, you are forcing him/her to solve problems that you could easily solve. If you provide the solutions, then you will create a better product experience for your User.

Fitting the product into the User’s life presents the writer with a duty and an opportunity:

* The duty to ease the User from what he/she previously did to the new product’s situation

* The opportunity to explain your product by using the User’s experience as a background.

OVERVIEW

To create an effective User Document, the writer must know who he/she is writing for. This article presents four dimensions (Skills, Attitude, Knowledge and Experience) for describing the User of your product (your Documentation Reader), and how to build a Persona that turns your generic User into an almost-real person. The article stresses the need to actually USE this information when structuring and writing your User Document.

GETTING INFORMATION ABOUT YOUR USER

The marketing department or product development team should be able to tell you who the intended User of the product is. (If they cannot, then the product is in big trouble.) Ask them to provide you with a complete description of the User. Ask them if their description can be make less strict (requiring fewer skills, ect.) and thus be applicable for a wider audience. Ask them how sure they are of their intended Users.

Ask them if they created a “Persona” (see below) to design the product. If so, ask them for the description of that Persona.

We will use this information to analyze your User in four dimensions. We will then re-build the ideal User into an almost-real person, who you can use to help design and write your User Document.

Timing: My estimate is that if the communication paths between you and the marketing and development teams are effective, then you should be able to complete this series of steps in a few hours spread over several days. This description of your User/Reader is an essential element in structuring and writing your User Document.

THE FOUR DIMENSIONS OF YOUR USER (Reader of your Document)

Four dimensions define your User/Reader. These dimensions are:

* Skills

What skills do you assume that your Reader must have in order to understand your User Document? (These are the skills that you assume that they have when they START to read your User Document… not the ones that you will teach them in the User Document.)

In a classic example of failure, a company that taught software programming did not specify that its students had to know how to use a particular computer word processor. As a result, students spent 80% of the class time learning how to use the word processor, rather than learning to write programs. The class was a failure.

List the skills that you expect your Reader to have.

* Attitude

Your Reader’s attitude is almost always a combination of anger (impatience at having to read this stuff instead of using the product), and fear (something is not working the way your Reader expects it to). Write with compassion for your Reader. Are there other attitudes that may affect how your Reader uses the product and your documentation?

* Knowledge

What information do you expect the Reader to have when they read your User Document? Is there something that you expect your readers to understand or to have to figure out for themselves? If there are such items, then you should tell your Reader where to get the needed background information.

* Experience

Skills plus practice, yields experience. Are there any experiences that you expect your Readers to have, so that they can understand how to use the product or understand what you are writing? BEWARE of your Readers’ experiences that may negatively affect how they use your product. One example is a product that radically changes the way that the User currently does things. Devote some space in your User Document to overcoming these problematic experiences.

WRITE FOR THE SAKE OF YOUR READER

These four dimensions spell out the word “SAKE.” This reminds us to write for the SAKE of our Readers. You use these four dimensions when generating the topics for your User Document, as well as reviewing the material that you have written. These are topics for other articles in this “New Technical Writer” series.

Make sure that you tell your Reader about any SAKE assumptions that you make about them. Thus if you assume them to have a special skill, such as “welding steel” then tell them your assumption early in the User Document. If possible, tell them where they can get the background SAKE items that they might need. For example, if you assumed that your Reader has the skill to identify a certain bird, then tell them were to learn to identify that bird (perhaps with a link or reference to a birding authority).

You want to avoid situations like the one in the example above: the unstated requirement for knowing a specific word processor that ruined a programming class. Is the assumption that everybody knew how to use that esoteric word processor a reasonable one? The course developers should have checked with their sales department, since they sold the course to students who could not possibly have known about that esoteric word processor.

You really must clearly state (early in your User Document) any out of the ordinary assumptions that you make about your Reader.

YOUR READER AS A REAL PERSON

From the SAKE dimensions, and from the descriptions of the typical User of the product that you got from the marketing or development teams, you will create a real-as-possible person to represent your typical User. Such a representation is called a Persona in the product development industry. The Persona is also your User Document Reader.

If the marketing and development teams use a Persona, and they provided a description to you, then use their Persona. You may have to add some description to it.

If you have to create a Persona, follow these steps (overview):

1. Imagine the generic User of your product.

2. Focus on this User. Describe the User. Think about his/her background, education, family, hobbies, interests. The goal is to make your generic User as tangible as possible.

3. Perhaps give the User a name, and even spend a minute or two to find a photograph of this Persona.

4. Evaluate for yourself if this Persona is a good representation of the User. Make changes as necessary.

Think about how the Persona got your product (for example, did they purchase it, did it come bundled with some other product, was it a gift, etc.). Think about what they are most likely to want to do with your product.

Later we will use the Persona to help define the topics of the User Document, and to help you write the actual text.

CHECK

Once you have generated the SAKE items and the Persona, write them out, and let members of the product and marketing teams check them for accuracy. “Accuracy” means “how closely your Persona coincides with their (product and marketing teams) view of the product’s User.” Discuss these points and make modifications as needed.

USING YOUR READER

Unfortunately most courses and books about technical writing stop here in their instructions about “knowing your Reader.” These courses and books expect you simply to keep your Reader in mind when you write.

But you can and should do much more with the description of your Reader. The Persona will help you structure the information in the overall User Document; it will also help you write each of the topics.

The SAKE dimensions will help you as you revise your writing. Here the SAKE dimensions will

* help you avoid using language your Reader might not understand, and

* help you avoid jumps in your writing that your Reader will not be able to make.

Other articles in the “New Technical Writer” series will describe how to use your Persona and SAKE dimensions to design and write your User Document. See the “Resources” or “Author Information” section of this article to find links to related articles.

Overview

Our humdrum, sterile headings and writing manner do little to encourage our Users to read parts of the product documentation that would be especially beneficial for them. This article presents two real-world examples, how they fail their users, and how to correct the problems.

Not the Legal & Disclaimers

Although the Legal and Disclaimer sections of your documentation are important for the protection of your company (and protection of your company should be a primary goal in your work), this is not what we are talking about here. Instead, we are discussing the Document topics that are often overlooked, but are important to your Users.

We will look at two examples where the Document writer should push the Reader to investigate additional material. My suggestion is to “advertise” the topics, by using tempting writing, to urge the User to read the relevant topics.

A Rule of (Writing) Life

If a User knows one way to do something, he/she is hesitant to bother learning about other ways. You, as a Document writer, have to sell the Reader on the benefits of the “other” (better) way.

Example: Microsoft Word ™ Styles

Most power users of Microsoft Word ™ use “styles,” rather than manual formatting, to format their documents. New and casual Users do not know about this powerful tool (available in most word processors ). Word’s User Documentation does little to encourage the User to learn about styles.

The Word’s User Document talks about manually formatting characters, paragraphs, etc. Later in the document there is a section on “styles.” But why should the User ever read that section? Styles seem to be just another way of formatting characters, paragraphs, etc. The formatting section just told them how to do this.

Power Users know that for anything longer than a few page letter, styles provide many benefits.

Documenter: Sell the Reader on important topics! Encourage your User to read the additional material. Microsoft should have added something like this at the end of the section on manual formatting:

“We recommend that you use ’styles’ to format any documents longer than a few page letter. See Chapter XX to learn about styles.”

Example: Gas Barbecue Safe Shut Down

A Gas Barbecue User Document headline says: “How to Shut Off Your Barbecue.”

The Reader Thinks: “I know how to do this,” and doesn’t read the material.

If your Users are doing things unsafely or incorrectly then that bland headline will do nothing to help them correct their ways. Let’s try a more convincing headline for this:

“Most People Shut Off Their Barbecues Unsafely: Here’s the Correct Way”

Or even more focused:

“You Probably Shut Off Your Barbecue Unsafely: Here’s the Correct Way”

This wording sounds like you are selling a product to the User. But you are not. You are using marketing techniques to get Users to read important material.

By the way: If you have a gas barbecue, compare how the instructions tell you to shut it off, versus how you actually shut the barbeque off.

“See Also” is too Bland

Don’t fall into the trap of simply adding “See Also” sections where relevant. These are OK for telling the Reader where to find additional information, but do nothing to convince your Reader to read important additional material. If the material is of real benefit to the Reader then sell them on reading it. Compare these:

* See Also: Styles, Chapter XX

* We recommend that you use “styles” to format any documents longer than a few page letter. See Chapter XX to learn about styles.

If you were reading the User Document, which of the above two headings would get you to learn about styles? (If you gave the ‘wrong’ answer, then ask some other people;-)

The Bottom Line

By selling the Reader on what you (or your subject matter experts) consider important (beyond the legal and disclaimer statements) you are adding your knowledge to the document. In effect, you are saying, “I think you should read this topic because it may help you.” That’s a good thing to say, especially because it reflects your good attitude to your Reader.

OVERVIEW

You’re a non-writer who has just been assigned to write the User Documentation for your company’s new product. Your overwhelming emotion is fear, perhaps with some anger.

With any new activity there will be some anxiety. Writing may have added anxiety because of your writing experience while you were a student.

Writing User Documentation is not like the writing that you had to do in school. Those activities were filled with anxiety and “writer’s block.” In this article you will see how to overcome your writing anxieties so you can write a good User Document.

WHAT YOU’RE NOT WRITING

All writing and writing situations are not the same. Let’s differentiate writing a User Document from other types of writing and writing situations.

YOU’RE NOT WRITING A NOVEL

You don’t have to worry about a plot, characters, and techniques to make the writing flow. You do not have to worry about transitions from one section to another; you don’t have to worry about continuity. It is extremely rare for your Reader to read a User Document from start to finish; Readers usually only look up the information that they need at the time.

YOU’RE NOT ARGUING A POINT

You don’t have to determine a point to argue, think up arguments to support that point, and then convincingly present the arguments.

YOU’RE NOT WRITING A LABORATORY REPORT

While lab reports provided a structure for writing, it was usually over-restrictive and those doing the grading were very picky regarding that format and structure.

YOUR SCHOOL-WRITING EXPERIENCES

At the end of your school writing exercise there was a critic (your teacher). Your goal was to impress him/her with your writing, all the time being extremely careful to write grammatically, and follow the prescribed structure. Later we will get a “critic” (editor) to be on your side in the writing project.

Writing a User Document is Different. The team is on your side. (I am ignoring office politics.) Everyone wants to have a successful product, and good User Documentation is part of a good product.

Remember that other members of the team are human, also. They have their tasks to complete, and would probably prefer not to have to answer your questions. Be prepared (read background info, etc) before you ask questions.

STRUCTURE MAKES WRITING EASIER

The overall structure of the User Document will follow the interaction between the User and the product. Within that structure you will write components…pieces of the User Document, each dealing with a specific topic. Each component will have a defined structure: overview/background, the actual material, and additional information.

One benefit of working this way is that you will not be concerned with “writer’s block.” The primary cause of writer’s block is having making decisions (”what should I say here?”). An effective writing structure eliminates most decisions, and reduces your writing task to almost “fill in the blanks.”

In fact, some experienced writers find it difficult to write in a modular environment. They are concerned with writing elegant transitions from one section to another. You do not need to do this…you can write each component totally independently of the others.

Your task is to clearly provide the information that your reader needs, and make that information easily accessible to him/her.

You must cultivate an attitude of compassion for your Readers.

YOU NEED RESOURCES FOR SUCCESS

Whoever assigned you the writing project (your “patron”) is responsible for your success. Your patron should provide resources to assist you. One of the most important resources is an editor.

EDITOR

Your editor (if hired early in the project) can help you over many writing difficulties. For example, your editor can help you with wording problems as you write. Consult with your editor as you are creating the User Document…not just at the end.

Your editor is not your critic!

Your editor will reduce your worries about grammar and wording. Your editor is on your side; he/she is not an adversary or someone you have to impress (like your school teachers). Your editor can help you produce a good User Document.

ACCESS TO INFORMATION

Your patron should enable you to have access to the product developers, information about the product (a mockup of the product, marketing information, assumptions about the Users of the product), and the industry.

TIME AND PHYSICAL RESOURCES

You need time to do a good job, and the physical resources to get it done.

If you are in a hurry, and if you do not know any of the current fancy authoring tools and content management systems, do not bother with learning them.

Instead, investigate what your word processor will do. Can it be made to create PDF, HTML, RTF or text files? If so, then it is a fine candidate for this project. Learn how to use its basic capabilities, especially its concept of formatting “styles.”

TRAINING/GUIDANCE

Typically, documentation is started late in the project’s life cycle. As a result, the documentation production is always rushed. Taking a live writing course may be out of the question: there will be scheduling problems, and you will be away from the writing task while you are being trained.

A better alternative might be to take a computer-based course that guides you through the writing, and supports you via e-mail. Visit the links in the “Resources” or “About the Author” section of this article.

YOU NEED A WRITING METHOD

To simply gather the required information, produce an outline that gets approved, and go off to write the document, is a recipe for high-stress and possible failure. It’s high stress because at the end of your writing, you get everything evaluated at once. There is the fear of failure. Fundamental errors could result in a major re-write. Aaaargh!

Consider writing components (modules, pieces) of your document. Let a component sit for a while, review it, and then circulate it for review. This way you will know that you are on track early in the project.

Since components will usually be short and focused on a particular topic, your reviewers will actually have the time to read and comment on your components. Just providing a complete, massive document at the end of the project will discourage your reviewers from effectively evaluating the material.

Writing and having reviewed small chunks of text (as opposed to creating the entire document, and then having it reviewed) helps reduce your stress, enabling you to do a better job.

Recall a skill that you have learned. It may be driving a car, riding a bicycle, or solving differential equations. Remember how you got more comfortable as you worked at it. It is the same with writing your User Document in components. The first few components will be high-stress, since you are new to the process.

As you write and have your components reviewed, you will become comfortable with the process. The later writing will go faster and better because of the reduced stress. Your review team will know where you are in the writing process; they will see each component as you release it.

Contrast this with writing the entire document and then having it reviewed. Here the stress builds to a maximum at the hand-in and evaluation time. You never know — until the end — if you’ve made a fundamental mistake.

DEALING WITH REVIEWS OF YOUR WRITING

You will have each component reviewed by others on the product project. Consider their suggestions and criticisms of your writing. However try to leave your ego out of the equation. If a reviewer says “you got this wrong,” you should hear “this is incorrect.” Ask what is incorrect, and get the correct information. Correct the inaccuracies. Don’t be defensive.

If you can overcome your fear of criticism, you will be able to write more and write better. This fear will diminish as you produce (and have reviewed) each of the components.

Learn as much as you can about the product, its environment, and Users. If you are expected to be an expert and are not one, then use the excuse for any naive questions you may ask: “I am just simulating our product’s Users with this question.” (Use this technique sparingly.)

TWO MORE POINTS

Nobody writes the perfect User Document. Don’t strive for perfection. Doing so will prevent you from getting anything done.

Read. Read all sorts of published materials, especially other User Documents (especially for products similar to the one you are writing about). Learn from that writing. Be critical of it from the USER’s point of view.

FIRST THINGS TO DO

Learn as much as you can about the product that you have to write about, its users, and the product’s environment, before you ask questions (other than where to get information).

Visit the links in the “Resources” or “About the Author” section of this article. There you will find articles and resources to help you through this exciting task.

OVERVIEW

Searches in User Documents (manuals, etc.) often fail because the Reader uses different words for a concept than the author uses. Since the Reader’s words do not appear in the document, the document search mechanism cannot find them, resulting in frustration. This article describes a User-friendly technique for improving searches, without having to change the Users’ behavior or the search software.

YOUR READERS’ WORDS

People use the words that they know when they speak, write, or search. It’s folly to try to force the Reader to use the writer’s terminology; the Reader simply might not know the “proper” term. Forced to use unknown words, the Reader will find the User Document to be arrogant, or at least difficult to use.

For example, a User Manual for a word processing program will probably use the word “formatting” when dealing with character fonts and size, as well as page layout. But suppose that your Reader uses the word “appearance” to refer to these topics. How can we get the search mechanism to provide the correct result if the Reader searches for “appearance”?

THE TECHNICAL ANSWER: A THESAURUS SEARCH

The technical solution would be to convert the document search software from being an “exact term” search to a “Thesaurus Search.” In a Thesaurus Search, the User enters a word that he/she knows, and the search returns synonyms or references to the synonyms in the document. Thus a properly set up Thesaurus Search should return references to “formatting” if the Reader searches for “appearance.”

Unfortunately, the Thesaurus Search is rarely available, and creating one would require changes to the existing search program. A low tech solution may be the best answer.

THE ANSWER: SYNONYMS

For this technique, you need to put synonyms of the author’s word (”formatting”) on the pages that you want the search to find. Such synonyms may include “appearance,” “design,” and “layout.” This is a simple, effective solution.

You can find appropriate synonyms by using the thesaurus that is a component of most word processors and of many libraries. Select the synonyms that your Readers are likely to use. “Likely to use” is based on your analysis of your Reader.

This leads us to the next question: How do you put the synonyms on the page?

DON’T USE HIDDEN TEXT

Technically savvy writers may ask “why not use hidden text for the synonyms?” The benefit is that hidden text will not “clutter up” the page.

So, if in the sections of the User Document where “formatting” is presented, the writer put the word “appearance” as hidden text (assuming the search utility would find this hidden information), then the following will happen:

1. The Reader searches for “appearance.”

2. The search takes the Reader to the “formatting” section of the document.

3. The Reader wonders “How did I get here?” The word that he/she searched for (”appearance”) does not appear on the page, since it is hidden.

Given that a goal of a User Document is to answer the Reader’s questions, then doing anything that causes him/her to ask another question (”How did I get here?”) is counter-productive. Hidden synonyms are not the best answer.

THE ELEGANT SOLUTION: “YOU MAY KNOW THIS AS…”

Hiding the synonyms is not a good idea. It’s better to let the Reader know what’s going on. The easiest way is to add a line of text on the page where the topic appears. This line of text begins with the phrase, “You may know this as…”

To continue our “formatting” example, our explanatory synonym phrase becomes, “You may know this as appearance, layout, or design.” A search for “appearance” brings the Reader to the “Formatting” section.

Upon seeing the phrase “You may know this as appearance, layout, or design,” the Reader knows why the search found this location. The search satisfied the Reader, and did not add uncertainty to the situation.

THE BOTTOM LINE

The goal of all good User Documents is to improve the Reader’s experience with the product. By using synonyms for “technical” terms, the writer makes the Reader’s document searches more effective, since the needed topics will be found using the Reader’s words.

By not hiding the synonyms, the Reader is not confused as to why he/she arrived at that place in the document. The result is a better experience with the document and the product.

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.

Overview

Incomplete User Documents disappoint your Readers. Two attitudes of many Technical Writers result in incomplete User Documents. These two attitudes are:

. “Everyone Knows That”, and

. “The User Can Figure It Out”

This article describes these attitudes and presents methods for overcoming them. The result is more effective User Documents and more satisfied Users.

1. “Everyone Knows That”

The “Everyone Knows That” attitude makes assumptions about your Reader’s knowledge. These assumptions cause your Reader grief.

Here’s an example of a possible “Everyone Knows That.” Do you know this:

Tomatoes. Most of us keep them in a refrigerator. However, storing them in a refrigerator will ruin the taste and nutrition of tomatoes. Tomatoes should be stored on a kitchen counter at room temperature, until they are cut. Once cut, tomatoes should then be stored in the refrigerator.

Does everyone know that? What do you assume that everyone knows about your product?

Sometimes your User Documents have to overcome previous User experience. Everyone thinks that they know how to properly (safely) shut off a barbecue…they don’t! The safe shutdown method is described in most barbecue User Documents, but it is not “advertised” (forcefully presented) in the User Documents.

It’s rarely true that “Everyone Knows That”. Just because you find something to be obvious, it does not mean everyone knows that something.

Here’s another example: How do you use a (combined product — ‘2 in one’) shampoo and hair conditioner? When shampooing, the shampoo is massaged into the scalp and immediately rinsed. When conditioning the hair, the conditioner is massaged into the hair, and remains on the hair for about two minutes. Now, what do the Users do for the combined product: rinse quickly, or let the product remain in the hair?

If you have the “Everyone Knows That” attitude when you write, you will tend to leave out needed material from your User Document. You will be doing a disservice to your Readers, and to your writing.

When in doubt whether “everyone knows something,” assume that they do not. Then,

. add some text explaining the topic, or

. tell the Reader where to find information that will explain the topic

Another Caution

Be careful about assuming that just because you explained something earlier in your User Document, your Reader will remember (or even have read) that information. It is rare for Users to read product documentation from start to finish.

When in doubt, add a reference to that earlier (background) information. Tell your Reader where to find it, or provide a link to it if your document is electronic.

Here’s a Thought Experiment: You are a User of products: How often do you read the product documentation from start to finish? If you always do, then ask some other people. (The great thing about this fact — that Users do not read the documentation from start to finish — is that it results in great flexibility in writing, formatting and editing the product documentation.)

2. “The User Can Figure It Out”

The User does not want to have to figure things out. The User is not reading a mystery novel or any other literature, where he/she wants to think about what is happening.

When someone uses your product, they are using it to meet their own needs. Your product may be central to your life, but to your Users, your product is a means to an end. And they do not want to have to decipher your product documentation.

Here’s a simple example. An e-mail tells you to call someone, but the message leaves out the phone number. You are expected to find the phone number on your own. The writer probably knew the phone number, but left it out. This “information oversight” gets expensive within a company when the e-mail is sent to many employees…each looking up the phone number on his/her own.

My favorite pet peeve: dates. Within recent memory we “survived” the Year-2000 transition. Yet we still write dates sloppily. We use “06″ for a year, instead of “2006.” When we see things like “07/11/04″ what is the date it is referring to? Is it November 4, 2007, April 11, 2007, or some other permutation of the numbers. The standards for the format of dates vary around the world. This is an example of both assumptions:

. “everyone knows that” (because there is a “standard” date format — there is not), and

. “the User can figure it out” (by seeing if my other dates provide clues to the format)

Don’t leave things for the User/Reader to figure out for themselves. It takes you only a few moments to include the material your Reader needs, and will save many Readers many hours in figuring things out.

Do It:

The writing literature tells you to “know your Reader.” Here is where you use that knowledge to improve your writing.

Either

. find someone who is like your intended Reader, or

. “do your best” to act like your intended Reader (you can do it if you need to)

In reading and evaluating the document, look for places where

. the writing assumes that “everyone knows that”

. the writing expects the Reader to be able to “figure it out”

. the writing makes jumps that your Reader cannot follow

. the writing makes the assumption that the Reader has read and remembered the entire document

Fix these places. It only takes a few words or sentences.

Everyone will be happier.

OVERVIEW

Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization.

If this documentation is not created or is poorly written, it costs you twice:

* The first cost (attributed to any poor user document) is the cost of answering the Users’ questions (technical support).

* The second cost, arises from the lost time of your employees trying to understand the poor User Document.

Psychological costs also affect both the external and the in-house User.

THE FIRST COST: TECHNICAL SUPPORT

This is the cost you incur whenever you produce poor (or no) User Documents. It arises for any User when he/she needs technical support. For external Users, the cost is your technical support staff, toll-free telephone lines, etc.

For internal Users the cost is the time spent by the developer or modifier of the tool to answer the questions of his/her fellow employee. This is an expensive technical support cost…these people are usually paid more than your technical support staff. Thus this first cost is even greater for poor in-house documentation than for shoddy documentation released to the public.

THE SECOND COST: USERS’ TIME AND RESOURCES

For Users outside your company, the second cost is assumed by the Users themselves or their employers. These confused Users are expending their company’s time: the time lost trying to get the product to work, and the time spent dealing with your technical support.

For your in-house Users, this cost is borne by your company. It is your employee–on your time– that is wasting your company resources trying to use an arcane product or document. Here is where your deficient in-house documentation costs you twice.

PSYCHOLOGICAL COSTS AFFECT ALL READERS

In addition to these time and monetary costs, there are the psychological costs wreaked by poor User Documentation.

For frustrated Users outside your company, your poor documentation results in a negative perception of your company and its products. This may result in loss of business.

For users inside your company, the psychological cost is decreased employee morale, as evidenced from these possible statements:

* Our company produced this junk?

* These people are not a sharp as I thought they were.

* If other employees can produce this confusing stuff, then I can work at that same level.

Thus the ill will outside your company can cost you future sales; the ill will inside your company can cost in decreased employee morale.

SOLUTION: INFORMAL REVIEWS

Once someone writes a User Document for an in-house tool, that document should be informally reviewed.

SELF-REVIEW

The author can perform the first review on his/her own.

Use your word processor’s spelling checker to correct common errors. You can use the word processor’s grammar checker, however most of these are inaccurate.

Before doing this review, let the document sit for a day or two. This will help you forget what you meant in your unclear writing. When you do the review and you find yourself asking “what did I mean here?” you will have found a place in the document that needs revision.

When doing the review, imagine you are user of the tool and reader of the document. Imagine the tasks that the tool user wants to do. Does the document enable the Reader to find what he/she needs? Is the writing accurate (correctly describes the tool), clear, and complete? Make the changes that would improve the document.

EXTERNAL REVIEW

Then, if possible, use an external reviewer (inside your company). To do this, the writer should:

1. Find a potential User of the tool. This should be someone who is not already familiar with the tool, and as similar to the target audience of the tool as reasonable.

2. Have that reviewer use the document to guide him/her in use of the tool. Solicit comments on the document. Note the suggested changes, additions, deletions, clarifications requested by the reviewer. Some questions to ask might include:

* Does the document tell you what you need to know?

* Is it easy to find what you need in the document?

* Does the document answer your questions? If not, what questions are unanswered?

* Is the document easy to follow? If not, where are the problem areas?

3. The writer should make changes as necessary.

If you cannot perform this “semiformal” review, then get anyone other than yourself to simply read the document, and make suggestions for improvement.

CAUTION

Make sure that the review process does not become an inhibition to those writing User Documentation for in-house Users. Stress a cooperative — not adversarial — mechanism whose result is quality work. Do not try to create the perfect User Document.

If you have great passion for words and have a degree or diploma in any technology field, then your chances of success is beyond your wildest imaginations. You can be part of that clan of writers out there, who make anything from a thousand dollars to several thousands every month from writing technical articles online for freelance websites, building their brands and getting noticed.

It’s a really wonderful field of writing. And, with the advent of Internet and web publication technologies, the traditional text publication platform has tasted a whole revolution. Today, as an author you are free to publish anywhere at your own will. All you need is some talent in writing, which most of us inherently have.

However, in order to succeed, the most important thing is your brand. You may be a great writer offline, you may know it yourself, and possibly, your nearest friends may know of this fact as well. But the world doesn’t, your prospective client doesn’t. In such a scenario, come the freelance websites. These websites give you a platform to show off your merit and get sales for the content you make.

Examples of the best freelance websites are Guru.com, Elance.com, getafreelancer.com, and so many others. You may just do a search from Google and you will stumble upon a million of them.

What you need to succeed?

One and the most important thing you need for success in freelancing industry is a flawless language and an extensive vocabulary. This will come about as a result of a lot of reading. But do not read any ordinary web publication. You should strive hard to find out the best publications to read. Those, which can enrich your mind, give you some thoughts, and give you new words and ideas. There are not too many of them. And I assure you, top bloggers may not get one sentence correct!

So, look out for authentic sources to read or those sites or blogs, which help you in writing. There are many.

Secondly, you should have quality content in your writing. Writing anything would not make you successful. The quality comes inherently. Naturally. All you have to do is understand what you are writing about and do an in depth research on the topic. Find out the important information on the technology you are going to write about:

It’s advantages and disadvantages

It’s issues and glitches

It’s benefit on the ordinary people

The ways people may use to tweak it to their advantage

The ways to use the tool productively

Any issue with particular groups of people: like children, adults, senior citizens, etc.

Any future improvements

The general statistics of the service provider and the service itself

In any writing about technologies hitting the market and those already in, these points are very important.

To do the research, you can use tools like Google. Do an in depth search for all the terms associated with the technology and find out everything available related to it. Once you get enough information, should read through it. Reading will generate more ideas in you, and will strengthen your points. Start your writing only after you read your research content.

Topic to find

You can find out the topic of writing by various means. The best way is by looking at the current technology news from Fox News, CNN, New York Times, Reuters, BBC World, etc. Such news channels and their websites provide you with the latest happenings in the technology field. What you have to do is read through a specific interesting post and find out the proper keywords. Then do an in depth research on these keywords with Google and Wikipedia. You can get a number of research pages to concentrate your writing on. And such content-rich articles are what the people want, and what hit high in search results. So, they will be purchased for any price you set on them.

All the best to all those who wish to get successful technical writing careers.