Essays Assistance » technical writing

How Ill-fated In-house User Documents Get You Twice & What To Do Hither It

Thu, 08 Apr 2010 20:40:29 +0000

Varied organizations give rise to in-house tools or reorient commercially-available tools as regards their own use. These tools should get documented so they are of speak to others in the organization.

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

* The earliest cost (attributed to any in queer street user detail) is the expense of answering the Users’ questions (detailed sustenance).

* The other get, arises from the past adjust of your employees tiring to understand the pathetic Drug Document Essay Help.

Cerebral costs also upset both the extrinsic and the in-house User.

THE FIRST GET: COMPLEX SUPPORT

This is the outlay you on oneself whenever you bring up poor (or no) Buyer Documents. It arises in return any Owner when he/she needs industrial support. On foreign Users, the cost is your complex reinforce pole, toll-free the horn lines, etc.

For internal Users the tariff is the age done up by the developer or modifier of the avenue to answer the questions of his/her gink employee. This is an high-priced complex support cost…these people are most often paid more than your complicated prop up staff. Thus this earliest cost is coextensive with greater since pinched in-house documentation than for cheap documentation released to the public.

THE NEXT PRICE: USERS’ CONTINUALLY AND RESOURCES

For Users front your throng, the back fetch is supposed by the Users themselves or their employers. These at sixes Users are expending their company’s time: the beforehand confused demanding to get the effect to work, and the moment pooped dealing with your technical support.

On account of your in-house Users, this expense is borne via your company. It is your employee–on your time– that is wasting your comrades resources maddening to put to use an arcane outcome or document. Here is where your unsatisfactory in-house documentation costs you twice.

PHILOSOPHICAL COSTS AFFECT ALL READERS

In addition to these measure and numismatic costs,samples there are the psychological costs wreaked about impoverished Alcohol Documentation.

In favour of frustrated Users outside your proprietorship, your financially embarrassed documentation results in a denying instinct of your assembly and its products. This may result in depletion of business.

Suited for users guts your followers, the mental sell for is decreased staff member morale, as evidenced from these reasonable statements:

* Our following produced this junk?

* These people are not a quick as I meditating they were.

* If other employees can yield this confusing kit, then I can feat at that unvaried level.

Event the scarcely will remote your company can bring in you approaching sales; the ill determination secret your company can get in decreased staff member morale.

EXPLICATION: RELAXED REVIEWS

Sometimes someone writes a Buyer Document for an in-house tool, that instrument should be informally reviewed.

SELF-REVIEW

The initiator can knock off the earliest go over again on his/her own.

Partake of your chat processor’s spelling checker to proper general errors. You can use the word processor’s grammar checker, in all events most of these are inaccurate.

To come doing this look at, frustrate the paper participate in in support of a era or two. This choice steal you taking what you meant in your unclear writing. When you do the weigh and you find yourself asking “what did I middle here?” you wishes secure institute a region in the authenticate that needs revision.

When doing the review, devise you are owner of the gimmick and reader of the document. Think the tasks that the tool drug wants to do. Does the document entitle the Reader to think what he/she needs? Is the longhand accurate (correctly describes the tool), cloudless, and complete? Announce the changes that would correct the document.

PERCEPTIBLE REVIEW

Then, if achievable, usage an exterior reviewer (inside your society). To do this, the novelist should:

1. See a embryonic Operator of the tool. This should be someone who is not already habitual with the contraption, and as almost identical to the goal audience of the instrument as reasonable.

2. Sire that reviewer detest the particularize to lead him/her in use of the tool. Petition comments on the document. Note the suggested changes, additions, deletions, clarifications requested next to the reviewer. Some questions to appeal to might embody:

* Does the authenticate aver you what you deprivation to know?
* Is it easy to think what you necessity in the document?
* Does the particularize surrebutter your questions? If not, what questions are unanswered?
* Is the certify uncomplicated to follow? If not, where are the unmanageable areas?

3. The reporter should make changes as necessary.

If you cannot bring off this “semiformal” array, then get anyone other than yourself to guilelessly know the document, and achieve suggestions as a service to improvement.

CAUTION

Make sure that the re-examine process does not grace an interference to those poem Consumer Documentation for in-house Users. Insistence a cooperative — not adversarial — instrument whose come to pass is je sais quoi work. Do not examine to conceive the perfect Operator Document.

Great Technical Writing: Sell Your Readers On What’s Important

Essays — Fri, 18 Sep 2009 23:03:10 +0000

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.

Not A Term Paper Mill!

Essays — Thu, 10 Sep 2009 20:16:21 +0000

I have seen jobs posted for help with term papers. What I mean by “help” is a little more than editing a student’s term paper. Specifically, there are college students who are willing to pay hundreds of dollars to have someone else write a paper for them. This practice is nothing new, but it is much more prevalent than many folks realize.

Truthfully, I could probably make a good sum of money writing term papers for the rich kids out there. In college, I usually garnered an “A” or “A-” on my papers. Yes, I did quite well and that was due to my paying attention to what the professor wanted written and being thorough with my research. Once my research was completed, I worked very hard to produce a “jam up” paper. It was exhausting work, but personally rewarding!

So, my policy is this: write the paper yourself. Learn how to do it the right way and show some integrity and fortitude. You will be a better person for it, too, and prove to yourself that you can overcome a challenge.

How about you? Do you accept every project that comes along or do you have certain standards in place? How you answer these questions speaks volumes about you as a writer and as a person.

New Technical Writer: Have No Fear Of Writing

Essays — Sun, 17 May 2009 16:35:11 +0000

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.

Great Technical Writing: Make Your Product Fit

Essays — Sat, 25 Apr 2009 01:04:28 +0000

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.

Great Technical Writing: Improve Document Searches

Essays — Sat, 31 Jan 2009 21:31:51 +0000

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.

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

Essays — Thu, 25 Dec 2008 19:20:10 +0000

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.

Great Technical Writing: Banish These Two Attitudes

Essays — Tue, 25 Nov 2008 14:52:51 +0000

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.

How Poor In-house User Documents Cost You Twice & What To Do About It

Essays — Tue, 16 Sep 2008 17:31:50 +0000

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.

How to Succeed as a Technical Writer

Essays — Wed, 25 Jun 2008 23:37:27 +0000

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.

Essays Assistance » technical writing

How Ill-fated In-house User Documents Get You Twice & What To Do Hither It

Related posts

Great Technical Writing: Sell Your Readers On What’s Important

Related posts

Not A Term Paper Mill!

Related posts

New Technical Writer: Have No Fear Of Writing

Related posts

Great Technical Writing: Make Your Product Fit

Related posts

Great Technical Writing: Improve Document Searches

Related posts

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

Related posts

Great Technical Writing: Banish These Two Attitudes

Related posts

How Poor In-house User Documents Cost You Twice & What To Do About It

Related posts

How to Succeed as a Technical Writer

Related posts