| OVERVIEW You're a non-writer who has just been | | | | working this way is that you will not be concerned with |
| assigned to write the User Documentation for your | | | | "writer's block." The primary cause of writer's block is |
| company's new product. Your overwhelming emotion | | | | having making decisions ("what should I say here?"). |
| is fear, perhaps with some anger. With any new | | | | An effective writing structure eliminates most |
| activity there will be some anxiety. Writing may have | | | | decisions, and reduces your writing task to almost "fill in |
| added anxiety because of your writing experience | | | | the blanks." In fact, some experienced writers find it |
| while you were a student. Writing User Documentation | | | | difficult to write in a modular environment. They are |
| is not like the writing that you had to do in school. | | | | concerned with writing elegant transitions from one |
| Those activities were filled with anxiety and "writer's | | | | section to another. You do not need to do this...you can |
| block." In this article you will see how to overcome | | | | write each component totally independently of the |
| your writing anxieties so you can write a good User | | | | others. Your task is to clearly provide the information |
| Document. WHAT YOU'RE NOT WRITING All writing | | | | that your reader needs, and make that information |
| and writing situations are not the same. Let's | | | | easily accessible to him/her. You must cultivate an |
| differentiate writing a User Document from other | | | | attitude of compassion for your Readers. YOU NEED |
| types of writing and writing situations. YOU'RE NOT | | | | RESOURCES FOR SUCCESS Whoever assigned |
| WRITING A NOVEL You don't have to worry about a | | | | you the writing project (your "patron") is responsible for |
| plot, characters, and techniques to make the writing | | | | your success. Your patron should provide resources to |
| flow. You do not have to worry about transitions from | | | | assist you. One of the most important resources is an |
| one section to another; you don't have to worry about | | | | editor. EDITOR Your editor (if hired early in the project) |
| continuity. It is extremely rare for your Reader to read | | | | can help you over many writing difficulties. For |
| a User Document from start to finish; Readers usually | | | | example, your editor can help you with wording |
| only look up the information that they need at the time. | | | | problems as you write. Consult with your editor as you |
| YOU'RE NOT ARGUING A POINT You don't have to | | | | are creating the User Document...not just at the end. |
| determine a point to argue, think up arguments to | | | | Your editor is not your critic! Your editor will reduce |
| support that point, and then convincingly present the | | | | your worries about grammar and wording. Your editor |
| arguments. YOU'RE NOT WRITING A | | | | is on your side; he/she is not an adversary or |
| LABORATORY REPORT While lab reports provided | | | | someone you have to impress (like your school |
| a structure for writing, it was usually over-restrictive | | | | teachers). Your editor can help you produce a good |
| and those doing the grading were very picky regarding | | | | User Document. ACCESS TO INFORMATION Your |
| that format and structure. YOUR SCHOOL-WRITING | | | | patron should enable you to have access to the |
| EXPERIENCES At the end of your school writing | | | | product developers, information about the product (a |
| exercise there was a critic (your teacher). Your goal | | | | mockup of the product, marketing information, |
| was to impress him/her with your writing, all the time | | | | assumptions about the Users of the product), and the |
| being extremely careful to write grammatically, and | | | | industry. TIME AND PHYSICAL RESOURCES You |
| follow the prescribed structure. Later we will get a | | | | need time to do a good job, and the physical |
| "critic" (editor) to be on your side in the writing project. | | | | resources to get it done. If you are in a hurry, and if |
| Writing a User Document is Different. The team is on | | | | you do not know any of the current fancy authoring |
| your side. (I am ignoring office politics.) Everyone wants | | | | tools and content management systems, do not |
| to have a successful product, and good User | | | | bother with learning them. Instead, investigate what |
| Documentation is part of a good product. Remember | | | | your word processor will do. Can it be made to create |
| that other members of the team are human, also. | | | | PDF, HTML, RTF or text files? If so, then it is a fine |
| They have their tasks to complete, and would | | | | candidate for this project. Learn how to use its basic |
| probably prefer not to have to answer your questions. | | | | capabilities, especially its concept of formatting "styles." |
| Be prepared (read background info, etc) before you | | | | TRAINING/GUIDANCE Typically, documentation is |
| ask questions. STRUCTURE MAKES WRITING | | | | started late in the project's life cycle. As a result, the |
| EASIER The overall structure of the User Document | | | | documentation production is always rushed. Taking a |
| will follow the interaction between the User and the | | | | live writing course may be out of the question: there |
| product. Within that structure you will write | | | | will be scheduling problems, and you will be away from |
| components...pieces of the User Document, each | | | | the writing task while you are being trained. A better |
| dealing with a specific topic. Each component will have | | | | alternative might be to take a computer-based course |
| a defined structure: overview/background, the actual | | | | that guides you through the writing, and supports you |
| material, and additional information. One benefit of | | | | via e-mail. |