Note: At the end of this Reading, I mention some assumptions about the other people on the product development team.
As you shall see, as you progress through this Course, it is important to know (or correctly assume) where your Reader is when they use your product and its documentation. You need to know this because you must tailor the topics and the writing to meet the needs of your Reader.
I need to make some assumptions about you. I hope that I have made them general enough that you fit into these assumptions. I will use these assumptions to guide my writing. And you will use the assumptions you make about your Readers to guide your writing.
I am trying to be as general as possible and using the most difficult set of assumptions that I am willing to deal with in this Course. For example in attitude about writing, I suggest that you might be unhappy about having to write.
You might be an engineer or scientist or developer or someone who does anything in your organization and got "stuck with" the documentation project. Your task is to produce effective documentation and to do it quickly. This Course will remove or at least reduce the stress of the writing task.
Alternatively, you could be someone who has been creating User Documentation for years, and wants to sharpen his/her skills. You will learn how to streamline the writing process and at the same time create more effective User Documents.
You might be the documentation manager for your organization. If so, then this Course will help you assist others in writing their documentation components, providing good User access, and in general avoiding the pitfalls that plague most User Documentation. It will also alert you to the background material (about the Users, the product and the purpose of the documentation) to enable your writers (in-house or out-house) to be the most efficient writers they can be.
I believe that you, as most people doing documentation, have little time in which to complete your task. To this end, I want to move you to the successful completion of your documentation project as quickly as possible.
You’ve done some writing for various Courses you have taken in school. These might include papers, reports, and other written assignments. Perhaps you have written something for publication. You might have liked the experience, or you might not have. What’s important is that you can think clearly.
Along with this I assume that you know something about the concept of an outline. The idea of major points, and sub points under them and so on. You might have done outlining when you were in school. I am not interested in whether or not you know how to number (label) an outline. I am concerned that you know how to organize your thoughts.
You also are able to verbally (by talking) explain the type of material you need to document. That is, if someone asked you to explain an idea (related to the product you are documenting) you would be able to do it.
You know how to use a word processor (or whatever software you will use to create your User Documentation). I suggest that you expand your skills when we ask you to learn to use the outliner capability that is part of most word processors. Perhaps we shall also have to break some bad (word processor) formatting habits you may have.
Alternatively, you may be an experienced technical writer, and are looking for ways to make you User Documentation more effective for your Readers. There are many important concepts in this Course for you. (See, I tried to cover all of the bases.)
If it bothers you to think of yourself as a “writer,” then don’t think of yourself as one. Instead think of yourself as someone who has to explain how to deal with your product. That’s what you are really doing when you “write” a User Document. User Documentation is the least expensive way to explain the use of the product to the User (another alternative is telephone support – that’s expensive).
If you are happy and excited about writing, then that’s great. This Course will be for you. You might skip over some comments that I make to “sell” the benefits of good documentation to my students. I truly believe that User support is vital to any successful product. Documentation is a powerful component of User support. (There’s one of those "advertisements" about the benefits of documentation.)
If you are so against having to write documentation that my efforts won’t convince you of its benefits, then all I can suggest is to use this Course mechanically. Follow the steps and you will produce effective documentation. However you must be understanding (compassionate) and have a goal of being helpful to your User in order to produce successful documentation.
You may be fearful about the project, having just been assigned an immense task: to document a large, complex product. You might have started to write something, but the words did not come. You might recall the results of the writing you did in school. For many of us that was a fearful experience; we viewed our Reader, the teacher, as an adversary. Your writing at school was usually intended to persuade the Reader. Your writing of User Documentation is intended to help the Reader. This Course will break the writing task into easily managed steps. A proofReader/editor will help you with your grammar and final wording.
Perhaps you feel writing is a bother...you’re an engineer, or programmer, or tool-and-die maker or whatever. Your job is to create a product, not teach people how to use it. Keep these thoughts; we’ll deal with them as we progress through this Course.
Thus your attitude might range anywhere
O From: You believe that documentation is a vital part of any product
O To: You believe that documentation is a necessary evil...something someone has to do because Users are too lazy to figure things out themselves.
In any case you want to, or need to, get the User Documentation written. I will assume you are somewhat negative about having to write User documentation.
(The result of this little assumption is that I will add comments throughout the Course to:
O Emphasize the benefits of good documentation,
O Demonstrate how being able to create such documentation is a valuable personal skill.)
In this Course you will learn how to break down, organize and effectively write your document.
There are some other components of your attitude that I hope you have or will develop over the Course of this project:
O Sensitivity to your Reader: Understand where he/she knows and feels, and what he/she is going through when they need to consult your document. (Surely, there must have been times when you have been frustrated because the documentation that you had to rely on failed you.)
O Flexibility: During this project you will be called on to learn new material (in the Course itself), work on your document, and sometimes learn and do things on the side. I hope that you can juggle these activities. If you cannot handle this juggling act, it will only slow your progress, but it will not result in failure of the project. Thus the flexibility is nice, but not mandatory.
While you know how to talk, you are not an expert at grammar. Don’t worry about that. You can do the writing, and get someone else to edit and proofread your work. We will discuss this further when we look at negotiating for resources.
You might be part of the project team, or you might be an outside writer contracted or otherwise assigned to write the documentation for the product. In either case we will investigate how to gather the information you need in order to write your document.
I expect that you will work diligently to get the project done. At no time do I want you to wait for something else to happen, while doing nothing in that valuable time. This Course has a lot of parallel activities going on. You always have something to work on here.
For example, I strongly suggest that you use a Style Manual (also called a Style Guide) in your writing. This is a book that makes the decisions for you about how to say various things in your document.
You will be asked to find out if your organization has such a Style Manual. If they do, then use it. If not then you get to spend about one hour going to a large on-line bookstore (such as the one named for the Acme River in South America), and find and order one for this writing project. That's one hour, not one day or one week.
AND you continue your writing work even before the style manual arrives. You will not sit and wait saying that "they said I had to wait and use a style manual before I could begin my writing." You will use the manual in your revisions. This will be after the Reader, product and document are described, the outline is completed, and much of the rough draft and sketches are done.
You will not wait. In your free time you will learn about your word processor's indexing capabilities (on your own, from the documentation for your word processor, and from Internet resources and other sources of information such as libraries and bookstores).
So on this project you will not wait for things to happen. You have a deadline. You will make things happen.
As I've said before: "Perfection is not just the enemy of good, it is the enemy of completion."
Decisions: Decisions are the hardest aspect of writing. Fiction writers have it worst. They have to decide everything about their characters and the environment. You are not writing fiction here. To make things easier, I have reduced the number of decisions on this project to as few as possible.
The other members of the product development team are smart people. There is a possibility that they could always figure out for themselves how to make something work.
I have my own psychological theory about how people behave. I call the theory Personal Trait Habituation. "Habituation" means getting used to something to the degree that you ignore it. (Think of may of the ongoing sounds around you as you work…you have become habituated to them, and easily ignore them. Think of the feel of your clothes on your skin…again habituation leads to ignoring the feeling.)
Personal Trait Habituation implies that you ignore your personal traits; you feel that your capabilities are nothing special and that everyone has them. In the case of those on the product development team, they are habituated to their general skills, experience, intelligence and also knowledge about the product.
The result of this Personal Trait Habituation is that members of the product development team have the attitude that the User:
· Knows the product
· Or can figure it out for himself/herself
This leads to User Documentation that does not satisfy your real-world product User.
My recommendation is to be aware of these beliefs in both yourself and the other members of the product development team. Do not let these beliefs handicap your User Documentation.
(c) 2006 Igetitnow! Training, Inc.