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.