By: Barry Millman

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.

About the Author:

Barry Millman, Ph.D., has a Bachelor of Science in Electrical Engineering (1966, Carnegie Institute of Technology) and an M.Sc. and Ph.D. in Psychology (Human Information Processing, University of Calgary). He has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker. For the past seven years he has been researching and creating resources to help organizations create great User Documents.

Visit: http://www.greatuserdocs.com/ for resources to help you create the User Documents that your Product needs and your Users deserve.

Visit http://www.greatuserdocs.com/ReadingRoom.htm for more articles like this one.

Article Source: ArticlesBase.com – How Poor In-house User Documents Cost you Twice & What to Do About it

by Barry Millman

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 — two-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.

About the Author:

Barry Millman, Ph.D., has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker. For the past seven years he has been researching and creating resources to help organizations create great User Documents. Visit: http://www.greatuserdocs.com/ for resources to help you create the content and access that your Users want and need.

Article Source: ArticlesBase.com – Great Technical Writing: Banish These Two Attitudes

Author: Ugur Akinci

Specification (spec) sheets are like maps for the captain of a ship or the blueprints for an architect. No project can start without first putting the specs on paper.

Here are two spec sheets with which a technical writer should be familiar:

Design specs – This is a document that builds on and follows closely the “functional specs” document. It basically describes what a product should look like when it is manufactured. It takes all the functions and detailed features specified in the functional specs sheet and translates them into a visual language.

For example, if the functional specs describe a configuration function, the design specs describe the button or the navigational link that should launch the configuration interface; what it’s colors and fonts should be; where exactly the fields and buttons should be placed on the dialog boxes; etc. Design specs may also specify a product’s maintenance schedule and the service requirements, etc.

Testing specs – This document specifies the unit and system integration testing that needs to be performed on the product before it is released to the market. This document sometimes also includes the testing scenarios (or scripts) that the test engineers should follow step-by-step to reveal the weaknesses and discover the bugs before consumers can find them.

Technical writers sometimes contribute directly by writing such testing scripts and actually participating in the tests as well. Testing specs and the testing results are precious since they reveal for a technical writer all the vulnerable points of a product and become the input for the Release Notes that accompany every major release of a product, especially in the software industry.

If you are interested to read more about technical writing as a career and how it can help you earn a steady living, visit http://www.learntechnicalwriting.com. You might be pleasantly surprised with what you’ll find out. Join the thousands who are already helped and inspired by this information provided by a Fortune 500 Senior Technical Writer. Visit today and claim your free report “How Much Do Technical Writers Make?”

About the author

Dr. Ugur Akinci is a Fortune 500 Sr. Technical Communicator http://www.technicalcommunicationcenter.com/

Article Source: http://EzineArticles.com/?expert=Ugur_Akinci
http://EzineArticles.com/?Technical-Writing—Why-Should-a-Technical-Writer-Be-Familiar-With-Design-Specs-and-Testing-Specs?&id=1894071

Author: Bryan S. Adar

Ralph Waldo Emerson (19th century American essayist) said that a foolish consistency is the hobgoblin of little minds. He thought that what he called a great person doesn’t have to think consistently from one day to the next. Maybe so, but a great tech writer does need to think consistently – and write consistently, too.

Being consistent is very important in all types of writing from memos to technical manuals. The area we’re looking at today has to do with using numbers, abbreviations, and symbols. Each of these elements can be written in a variety of ways. For example: five feet, 5′, 5 ft., five ft. They all mean the same thing. Which one a writer uses is important, but using them in a consistent way is just as important. Five feet in one place should match five feet in another. This is poor usage: Five feet is enough space in front, but 5 ft. doesn’t allow enough space behind.

A style that is often suggested is that in documents where a word like foot shows up only once or twice, it’s written out. In documents where it appears multiple times, ft is better usage. That may be the writer’s call, or it may depend on the client’s style guide.

In the following sentences, it’s up to you. Use the style you prefer, but be consistent. Then, write a “rule” or “rules” that cover the situation. We’ve provided one preferred way of writing each sentence.

Example: We’ll arrive on 25 April and depart 06/05. We’ll arrive on April 25th and depart on June 5th. Rule: Be consistent in how you write dates. Rule: It’s safer to spell out month names.

1. The winning fish weighed 16 1/2 lb and was about 1.75m long.
2. These units are called MHz.
3. The base units come in boxes of ten @ a quarter each or $2 per box. measurement, or of specific importance.
4. 27 hourly employees will be involved in the transfer.
5. Check the % of items with values of less than .75.
6. The shipment will arrive between 11:00 am and 14:30.
7. Be sure the space is at least 6 1/2″ wide, 5.75 in. deep, and 11 inches long.
8. Use 300 pounds of type one, one thousand lbs of type 2, and 2 thousand kg of type three.
9. We need 50# of #5 widgets stet.

Exercise – Answer

1. The winning fish weighed 16 1/2 lb and was about 1.75m long. The winning fish weighed 16 1/2 lb and was about 5 3/4 ft long.
   Rule: Don’t mix metric and English measures.
2. These units are called MHz. These units are called megahertz (MHz).
   Rule: Write out the full word with the abbreviation in parenthesis the first time it’s used.
3. The base units come in boxes of ten @ a quarter each or $2 per box. The base units come in boxes of 10 at the cost of 25 cents each or $2 per box.
   Rule: Use numerals when the amount is a key value, an exact measurement, or of specific importance.
4. 27 hourly employees will be involved in the transfer. The transfer will involve 27 hourly employees.
   Rule: Don’t begin a sentence with a numeral.
5. Check the % of items with values of less than .75. Check the percent of items with values of less than .75.
   Rule: Use symbols only with specific values, not as a substitute for the word.
6. The shipment will arrive between 11:00 am and 14:30. The shipment will arrive between 11:00 am and 2:30 pm.
   Rule: Don’t mix 12-hour and 24-hour time designations.
7. Be sure the space is at least 6 1/2″ wide, 5.75 in. deep, and 11 inches long. Be sure the space is at least 6 1/2″ wide, 5 3/4″ deep, and 11″ long.
   Rule: Use abbreviations consistently. Rule: Don’t mix decimals and fractions.
8. Use 300 pounds of type one, one thousand lbs of type 2, and 2 thousand kg of type three. Use 300 lb of type 1, 1,000 lb of type 2, and 4,400 lb of type 3.
   Rule: Use numerals when the amount is a key value, an exact measurement, or of specific importance. Rule: Don’t mix metric and English measures.
9. We need 50# of #5 widgets stet. We need 50 lb. of no. 5 widgets immediately.
   Rule: Write out symbols that have more than one meaning.
   Rule: Avoid abbreviations that are not universally familiar.

If you can write a simple sentence in English and organize your thoughts then technical writing may be a rewarding field. You can easily make it a second income stream in your spare time.

According to the U.S. Department of Labor, the average salary for technical writers is $60,380. Freelance technical writers can make from $30 to $70 per hour.

The field of technical writing is like a golden city. It’s filled with wealth, rewards and opportunities. After learning technical writing you can branch out into business writing, marketing writing and communications writing. All of these can become additional income streams.

But to succeed you must learn how to market yourself to clients. You have to prove to them that you are an invaluable asset. That’s where ProTech – Your Fast Track to Becoming a Successful Technical Writer can help. It’s a technical writing course that does two equally important things:

1. It teaches you the skills to become a technical writer in the shortest time frame. You’ll learn to create manuals, procedures, tutorials, processes, proposals, spec sheets and other documents that businesses need.
2. It shows you how to market yourself to clients so you can start your income stream as soon as possible.

In fact, you’ll get a complete marketing toolkit which has templates and technical writing job sites to get started immediately!

You can download two sample lessons by clicking the link below.

This could be your chance to create a prosperous future.

Click the link below to download your two sample lessons.

https://www.techwritingcourse.com

Article Source: http://EzineArticles.com/?expert=Bryan_S._Adar
http://EzineArticles.com/?Learn-Technical-Writing—Exercise—Consistent-Use-of-Numbers,-Abbreviations-and-Symbols&id=1458926