Essay Online

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

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

For small companies, creating their product’s User Documentation in-house, provides benefits to the company, to (idle) staff, and to the product. This article describes the benefits and some downsides of producing User Documents in-house.

THREE OPTIONS

If you have no in-house writing staff you have three options:

1. No User Document for the product. This is NOT a valid option. Every product needs User Documentation. It completes your product package, and enhances the User’s experience with your product. Here are two examples of non-existent User Documentation:

* Tomatoes. Most people don’t know that before use, tomatoes should not be refrigerated. Refrigerating tomatoes before use will reduce their flavor and nutrition value.

* A Manual Can Opener. This can opener clamps on the can, thus the user does not have to squeeze the handles while operating the can opener. It came with no User Documentation, as “everyone could probably figure out how to use it.” This is wrong. After a few uses, the blades become slightly dulled, and the handles are very difficult to clamp and lock.

The simple tip of turning the knob while squeezing the handles makes the can opener easy to use. That tip could form the basis of a User Manual for the product. The manual should include instructions for care of the can opener. The absurd situation is that this clamp feature was the unique aspect of the product; but the feature becomes unusable because of no User Document.

How have you felt about products that came without User Documentation? Were you confused about the product and getting the most from it? User Documentation adds to the value of the product. Let’s look at how we can get it created.

2. Use an outside writing service or consultant. Technical writers may be an excellent choice to create your User Documentation. However, there may be downsides to using them.

* When documentation changes have to be made, the company has to re-hire the writer. If the writer were unavailable, then you have to wait or search for a new writer. When the new writer gets hired, a new orientation to the company and the project would have to start. Delays, delays, delays.

* An even more horrible thought is that the outside writer used some fancy piece of software to create the User Document, and you do not own that software. Thus you could not make any changes until you bought and learned that software, or hired an outside writer who uses the same software. (Most technical writers are enamored with a particular piece of esoteric writing software.)

Using the outside writer will force you to batch your documentation changes, making the literature out of date. (How many times have you seen product documentation that does not match the product? This happens because the company was waiting for the next major upgrade to update the User Documentation.)

3. Using idle employees in your company to create the User Documentation. The remainder of this article will focus on this option.

STAFFING BENEFITS

In most organizations, there is some staff down-time. By assigning these staff to create User Documents you benefit from effective use of this down-time, and the employees benefit from experience in a new field.

These staffing benefits include:

* Use staff who may be idle between projects

* Your staff know the company’s culture and their fellow staff

* Your staff use existing company-wide writing tools (your word processor)

* No time needed to get oriented with the physical aspects of the job

* You have created a new resource within company

BENEFITS TO YOUR USER DOCUMENTS

If you have in-house writers (even if they are not formally trained as “technical writers”) you can just say “Sue, could you or Tom update the document where the sign-in window is presented.” Much faster and more flexible then having to go to an outside source. Sue and Tom have ownership of the document, and would work to improve it. They would use software resources available in your organization.

The benefits of in-house writers to your User Documents include:

* You can make corrections as you find the errors.

* You are able to update your User Document when you update your product.

* Better control of timing and resources

* No fear in dealing with the User Document in electronic form. From your word processor or add-ins, you can publish your User Document as a portable data format (.pdf) file, or as HTML for display on the Internet.

DOWNSIDES OF IN-HOUSE WRITING

The primary downsides of in-house User Document creation are the attitude and emotions of your newly-appointed writer. These include:

* Fear (”I don’t know how to write”)

* Anger (”Why me? This is unfair”)

* Uncertainty (”I don’t know what to write”)

* Isolation (”I’ve been cast into this writing thing”)

You can reduce these negative emotions if you encourage and support your New Writer.

SUPPORT YOUR NEW WRITERS

It is unfair to assign a non-writer to create a User Document without supporting him/her. You have to support your writer with:

* Training;

* Access to the development and marketing teams for product information;

* Use of the development team to evaluate their writing (small chunks);

* Access to the product, industry literature, and marketing materials;

* Style manual;

* Editor — your writing expert;

* Time to do a good job.

Other articles in this series (see the links in the “Resources” or “About the Author” section of this article) present more information about supporting your New Writer.

The User-Product Life Cycle (U-PLC) is a powerful tool for the User Document writer. Use the U-PLC to generate the high-level topics for your User Document.

THE USER-PRODUCT LIFE CYCLE (U-PLC)

Usually, when we think of a Product Life Cycle, we think in terms of the development and production of the Product itself. When writing User Documentation, consider the U-PLC to help you generate all the topics necessary for a complete document. User Documentation should support your Users in all of their interactions with the product.

The User-Product Life Cycle refers to the full range of interactions between the User and the Product itself. This is more than simply “how to use the product.” As you will see below, “Use the Product” is only one stage in the U-PLC.

STAGES IN THE U-PLC

Here are the stages IN the U-PLC (assuming that the User as acquired the Product):

– U-P LC Stage: Transport the Product to its working location

– U-P LC Stage: Unpack the Product

Transport and Unpacking of the product are listed here just for completeness. These are currently displayed on the packaging itself, usually in pictorial form, and do a good job.

– U-P LC Stage: Overall knowledge about the Product.

This is information that is presented to the User early in the User Documents.

Topics here include safety, legal, and disclaimers related to the product.

The description of the product should indicate how the product may change the way that the User currently does things. For example, an analog voice recorder will require the User to listen to all the stored items to find a particular one; a digital voice recorder will enable the User to quickly jump from one message to another.

– U-P LC Stage: Set up or Install the Product

* Environments

It is important for the writer to think of the various environments where the product will exist. For example, how should a computer program be installed in a Windows, Mac, or Linux environment?

“Environments” includes other things that the product must work with. For example, how should a DVD player be installed in a system currently composed of a TV and a VCR? How about installation to a TV & VCR system where the TV has only one video input?

* User Capabilities.

The capabilities required for the User to set up the product are also important. Since the assumptions related to the User for set up may be different from the assumptions about the User in using the product, the wise writer will present the skills (and perhaps regulations) needed to set up the product. A section entitled “Can You Set Up This Product?” will enable the User to make the decision about whether to set the product up themselves, or find outside help.

For example, suppose the product is an electrical light dimmer that is intended to replace the light switch in the User’s home. Using the product merely requires adjusting the dimmer’s single control to set the desired light level. Installing the product requires experience with home electrical wiring–does the User have these capabilities?

Sometimes, the limitation may be legal. In some jurisdictions — Quebec, Canada, for example — only qualified electricians are permitted to install or modify electrical circuits in the home. Thus in Quebec, the general User of the dimmer will not be able to (legally) install the light dimmer.

– U-P LC Stage: Use the Product

This component is the focus of most User Documentation. It should contain at least these three sub-topics:

- Starting the product

- Actual Use of the product

For most products “Actual Use” is the central focus of the User Document.

Ideally, this should be divided into basic or common product functions, and advanced functions. A good example is photo-editing software. Most Users want to crop, rotate, and adjust the brightness and contrast of the image. These are basic functions. More advanced functions might be combining the parts of one picture with another.

- Shutting down the product

Is there any maintenance to be done at shut down? List it here and in the “Maintain” section.

– U-P LC Stage: Maintain the Product

Consider breaking this down into time periods, such as: after each use, weekly, monthly, yearly, as applicable.

– U-P LC Stage: Move the Product

For a computer software program, how the User should move the program and its data to another computer; computer users often upgrade their computer hardware. While it is often assumed that the User should re-install the product on the new computer, there always is the question about moving the data related to the product: where is it located, and how should it be moved so the newly-installed program can recognize it on the new computer?

For a physical product, are there any special considerations in moving the Product to another location?

– U-P LC Stage: Discard the Product or its By-Products

Here I would like to mention only selling the used product. It might be wise to mention that by keeping the User Manual, the seller may find it easier to sell, and possibly get a higher price, for the used product.

USING THE U-PLC IN YOUR WRITING

As you generate the topics for your User Document make sure that you keep the U-PLC in mind. Ensure that you include topics in your User Document Outline to assist your User in all phases of the U-PLC.

Great User Documents can assist in the UP-LC section that I did not present here: acquisition of the product. Your marketing department may be able to use your GREAT User Document as part of its marketing campaign.