|
The Structure of Your User Document
The Structure of Your User Document Table of Contents for this Reading Sections of Your User Document Your Document’s General Sections In Greater Detail: Products with A Continuum of User Skills and Needs Products with Different User Populations Warranty or Guarantee Information In this Course You Will Write Your Document Based Upon these Guidelines: Some Modifications to these Section Types.
This Course is a template or formula for creating a great User Document for your product. In this section we will see an overview of how your User Document will look that you create it in this Course. The document that you create in this Course may have the components I describe in this section. The components you choose to include will depend upon two things: 1. Your product. If your product requires a lot of support in its usage, then the usage sections will be larger than for a product one where the User Document needs only instruct the User on how to set it up. A word processor program requires a document with a large amount of usage support; the instruction manual for assembling a chair or barbecue requires little or no usage support. Thus the sections in your document will be based on the needs of the User in dealing with your product. We’ll discuss more about this at the end of this section. 2. The limitation of the size of your document. If your product is a simple, inexpensive device, then you might have to compress the entire User Document into a small space. We talk about this later in our section on Brief User Documents. You cannot arbitrarily decide what sections (which we
describe here) to include and what to exclude from your User Document. You must complete the analysis -- as we do
in this Course -- before you can determine what should be in your User
Document. In general every User Document will (in theory) have the sections that I will present in this part of the Course. Depending on your product and the amount of room you have to write the document (it may be a label on a bottle or a 500 page manual), you will modify or leave out some of these sections. However, your analysis should deal with the possibility of including all of these sections in your User Document. Ponder these questions (especially if you feel that the sections I will describe might be overkill for your document): O If you have not analyzed all of the material that you might tell your User, how do you know what to include and what to ignore in your document? O If you have the material for a 50-page User Document, but only have a small amount of room on a label for your User instructions, what are you going to do with the additional information? (I suggest putting this on a company website, and making your product an Internet Supported Product.)
Publication of Your User Document Here are the General Sections in your complete User Document. I will discuss these in this part of the Course, and analyze and design our document based on these sections (throughout the Course): Sections of Your Document (Cover or Splash Page) Read This First If You Are…Read This… User Document Overview About the Product Assumptions About You, the Reader About this Document and How to Use It Educational Material: Setting Up the Product Using Your Product Starting and Shutting Down the Product Using the Product What the User Should NOT Do with the Product Care, Maintenance, Storage and Disposal of the Product or its Byproducts Additional Information Index Cover or Splash PageA Cover will be for printed documents only. For a User Document that is electronically distributed, the material I describe for the Outside Front Cover could be displayed as the first page (or a splash page) of the electronic document. The material that I will present for the other three covers of a printed document (inside front cover, and the inside and outside back covers) can be placed on a page and accessed with links (perhaps as a footer) from each page in an electronic document. The cover is optional, especially for very short User Documents. However, if you do have a cover, its goal should be to help the User to identify the product and to connect the product to the document. Thus the Outside Front Cover should include: O Picture of the Product O Name of the Product O Name of the Document, Document Date O
The Web Address where the User can find more
information about the product O Where to get support for the product (technical support help) O Requests to “keep this document” and “read it over before using the product for the first time” O Direction to product safety information in your document (something like “See page 2 for important safety information”) O OK, and some slick graphics, but don’t let the slick graphics get in the way of the information that the cover must convey to the Reader O The package (the box, blister pack, or whatever the potential purchaser can read when shopping for your product) should indicate what the User must have in order to use your product. For example, if the product is a software product, then what computer operating system (such as Windows or Mac) the User needs. If the product is battery operated, the package should indicate what batteries it uses and whether or not they are included.
Acme does it Wrong.
Over the years, I have had several Acme digital watches. I always keep the manuals. Unfortunately, Acme identifies the manual
with a phrase like “Acme Module No. 1477.”
My watch is known as a “DataMaster 150” but that wording is nowhere to
be seen in the manual. In addition,
there is no overall picture of the product to help me distinguish this manual
from the one for the DataMaster 100 (which I used to own, but still keep the
manual that came with it). The Inside Front Cover should include definitions of symbols used in the graphics in the document. It might define the notation used in the document, and perhaps other "using this document" assistance. The Inside and Outside Back Covers could provide information that helps the User find things in the document, or be a quick-reference card. Alternatively, the outside back cover could include product warrantee or guarantee information. Leaving these areas blank is a waste of good document real estate. These are places that the Reader can find quickly and refer to easily. Don't leave them blank. "Read This First" SectionIn this section you will provide the following information (as is relevant to your product): O Safety precautions O Legal information and Disclaimers O Any Other legal information related to the product or industry O Warnings regarding product usage and misuse O Preventing Product Malfunctions O Reference to Certifications (which actually should be listed in an Appendix to the document, not in the first few pages of the document). However, government regulations require these certifications to be early in the User Document. For example, Federal Communications Commission – FCC – electronic product interference certifications are usually placed at the beginning of the User Document. Do not violate these requirements! O Overview Information (brief overview, optional) O
Troubleshooting: Where to Find Solutions to Your
Problems with [the product] O The next step (after reading this section) to take in using the product O How to use this User Document O A guide to finding things in the documentation set O
Where to get support for questions, repair, etc. If You Are…Then Read this…This section is useful to direct your Reader to specific topics in the User Document based on their SAKE, especially with the product itself. For example your “If You Are…Then Read this…” section might direct: O New Users to a Tutorial O Users of Competing Products to a section on differences between your product and the competing product O Users going from a free to a licensed version of the product to a section describing added features and other changes O Users of previous versions of the product to a section describing the changes to the product and how it affects these Users
User Document Overview(We gathered much of the information for this when we wrote the Document Specifications. Just read this section quickly.) The Document Overview has these major functions: 1. It must serve as an Introduction of the Product itself 2. Describes who the User Document is for; what the Reader must know, etc to understand the document or product 3. It must serve as an Introduction for the User Document The technique I present in this Course for creating the Document Overview ensures that it will meet these requirements. The Overview for the document itself should include these components: O About the product and how it affects the User O About the User: our assumptions about the User as they begin to use this document (you might choose to exclude this from your document, but you should still write this component for yourself and keep it in mind as you generate topics and review your writing). O About the document itself: O How to use the document O What the document covers (goals and purpose of the document) O What the document excludes; possibly where to find that excluded information.
You will sketch out this portion of the Overview as part of the User Document Specifications. When the document is completed, you will finish this section, describing the items that make up the document. We do this, as we progress through this Course. This section also describes where and how this document fits into the universe of the product. That is, what this document does, and just as importantly, what it does not do. How does this document relate to all support that your organization provides for the User? The entire User Document Overview will be about one page long. Educational MaterialPreparing to Use The ProductThis section includes setup and installation of the product. It should tell the User everything they need (additional materials not included with the product) to set up the product. You might argue, and argue correctly, that the
"Preparing to Use the Product" (at least as far as setup and
installation are concerned) will be done only once by a User. Thus to put this section early in the
document might be a waste of valuable document "real estate." As a result, you might wish to put this
section as an Appendix to the User Document, or as a separate "Setup
& Installation" document. You should list the additional materials that the User needs to use the product where the potential User can see them before buying the product (on the packaging for the product). The Acme Shoe Guarantee. I just saw a box that Acme shoes come in. The only text on the box (other than
identifying the product and its size) is concerned with the guarantee (pretty
standard one-year guarantee.) Using Your ProductHere is where we get into the main part of the "educational material" of your User Document. Other than for setup, this is where you help your User to be effective with the product. Ultimately your complete User document set (that means "all of the User documentation that we produce for this product") has to present all of the features of your product and how to use them. Whether they are presented in a single User Document, or separate ones is not important here. For example, a high-powered word processor might have a: O User Document that explains use of the product, O But uses a separate document to describe its internal programming language, O And a third document might describe how to set up the word processor.
I would like to offer two things to think about.
This section can be divided in either of two ways, depending upon your User population. For some products there is a continuum of User skills and needs. For example a word processor will have basic and advanced Users. However, all Users of word processors use the basic operations (such as entering and editing text, printing, saving the document, etc.). For other products there will be different populations of Users. My example of a "leave System" (that keeps track of employees' time off work) has two distinct User populations. There are the employees who request leave, examine how much leave time they have taken, etc. The other population is the manager. These Users approve leave applications, examine all the leave taken for their employees, and perhaps provide summary reports of leave. For products where there is a continuum of User skills and needs, I suggest dividing the "Using the Product" section into "Basic" and "Advanced" usage. I believe the following, and I hope I can convince you
of the same. There is a blurred line
between this category (“Basic Operation”) and the next (“More Advanced
Operation”). I only choose to
separate them to make things easier for the writer and the Reader. Products with A Continuum of User Skills and NeedsBasic OperationsFor most Users, and most products that those Users use, there is a set of basic operations of the product. For example, for a word processor, most people want to do simply write and print a document. To do that, they need to do the following O Work on a new or existing document O Add and manipulate text O Format the text O Save the document O Print the document
For a digital camera, the core set of operations would be O Take Pictures O Review/Delete Pictures O Displaying the Pictures O Uploading the Pictures to a Computer O Printing Pictures
For a Digital Video Disk (DVD) player these sections might be: O Playing a Video DVD O Playing Music CD’s
Think about the products that you use in your daily life. In most cases, you use a set of basic functions. You do want to know about and how to use the advanced product functions, but you do not want information about these advanced functions to get in the way of learning about, and using, the basic, frequent operations. You also want to know that these advanced functions exist in order to help you. Thus in the description of the frequently used functions, your User Document should indicate that the relevant advanced functions do exist, and where the Reader can find descriptions of these advanced functions (in the User Document, of Course). And one more thing…. this and the next “section” (Advanced Operations) might or might not appear as separate sections in your document. We simply want to describe the frequently used functions first, and the "fancier" ones later. More Advanced Operations (Fancier Features)Beyond the basic wants, interests and needs of the User are all of the fancier features and capabilities that your designers included in the product. These “fancier features” should be presented after the basic features. Reminder: But be careful here. When you describe a basic feature, such as “formatting” for a word processor, you should refer (via links or page number references) to any advanced features that are related to that basic feature. To continue the “formatting” example, the description of text formatting in the Basic (Usual) Operation area of your document should mention something like: “While these methods of manually formatting text are effective for small documents, you should learn about using styles [this is a reference or link to the styles section of the User Document], when you deal with larger documents. Styles benefit you by providing: O consistent formatting, O the ability to change the formatting of all of the text of that style easily, O and the ability of the word processor and related software to “understand” the structure of your document, making it easier to produce a Table of Contents.”
Learn about styles here … [this is a reference or link to the styles section of the User Document]. (Notice that I present the link to [this is a reference or link to the styles section of the User Document] twice. I don't think that the repetition is troublesome here. It enables the Reader to jump to the styles information when he/she first reads about it, rather than be concerned about "where is that styles information." That's just my opinion. In the “Advanced Functions Section” you would describe styles, their benefits and use. Later you would provide a chapter on templates, which are skeletons for documents and include styles. Products with Different User PopulationsWe will divide the Using the Product section of the User Document by User Population. Thus in our example of the leave system, we will have one section for Employees and one section for managers. Care, Maintenance and StorageO Care, Maintenance, Storage, Transport O Disposal of Byproducts O
Disposal of the Product Additional InformationO
Internet Supported Product O Appendices (referenced within the document itself) O All messages and their explanation (including menus & screens, beeps and lights) O Troubleshooting O
Adjusting Parameters O Technical Information about the Product O Where to Get More Information (incl. Bibliography) O Glossary
Important! You
should be gathering the information for many of the Appendices (for
example, the Glossary and Bibliography) as you write the document itself. Don't wait until the end of your
documentation project to create the Appendices.
Warranty or Guarantee InformationThe legal department in your organization will probably produce the text for the Warranty. If your organization has no legal department, then you could consider copying an existing warranty, or writing one of your own. Be careful, a warranty represents a contract between your company and the User of the product. Make sure that the warranty clearly states O What the User must do to keep the warranty in effect O The length of the warranty O The options of your company in exercising the warranty ("we will repair or replace the item, as we determine") O Any other warranty conditions and limitations O How to contact the company or repair facility in order to exercise the warranty. Have the warranty checked over by a lawyer to ensure that it is safe for your company. Warranty information could be placed on the back cover (inside or outside cover), as a separate sheet, or somewhere in the document. It should be referenced in the document's Table of Contents, to help the Reader find the warranty. O
Written based on the Users’ Wants, Interests
and Needs O Written based on the Skills, Attitude, Knowledge, and Experience of the Users O
Easy to Find the Information in It O
Easy to Read O
Easy to Follow Steps O
Easy to Understand Your document will provide information to the User in all phases of his/her use of the product. These include: O Problems and their solutions, O Explanation of what’s going on, including technical information, and O Tips on how to best use the product. The User Document for certain products will not have all the generic sections I just presented. Some of the sections will be renamed (and given different meaning), and other sections might not even exist in the User Document. For example, a document which tells a new owner how to care for a plant will have its “Preparing to Use the Product” section renamed to something like “Creating the Proper Environment for Your Plant.” Similarly, the “Basic Use of the Product” section would become the “Plant Care” section. This would provide instruction about the weekly and monthly care of the plant. The equivalent of the “More Advanced Operation” might deal with “Plant Problems and Special Situations.” A second situation would be an item that you might assemble, but need no instruction in its actual use. One example is a set of bookshelves that comes as a kit. The “Preparing to Use the Product” would be renamed “How to Assemble Your Bookshelves.” There might be no “Use” sections in your document, but there could be information in the “Care and Maintenance” section of the document. If you think about the above material, you might get the feeling that the Basic Functions might appear to be a tutorial. In fact, this is close to the truth…we shall blur the distinction between the tutorial and the User manual for the document you create. But there are some differences between a tutorial and the kind of User Document you will be writing. Typically the tutorial presents a brief overview of the function. When we write the “Basic Functions” section of our document, we shall present the relevant material in its complete depth. For example, for a word processor User Document, a tutorial describing formatting might provide one simple technique for formatting text. Our User Document’s formatting section would present all of the material related to formatting. It would not be a brief overview, with the in-depth information to be presented later. Continuing with the word processor example, we will present everything about text formatting when we present the concept of “formatting.” We probably would save page and section and document formatting for the “advanced” use sections. The point that I am trying to make here is that the "Basic Operations" section of your document is not to be an overview, with the detail material to be presented later (as is done with a tutorial). Instead, your document will have the complete description of the basic operations in the section where you present the basic operations. As I mention in a later section of this Course (Types of User Documentation) the tutorial style is more conversational than a full User Document. I prefer that we keep the conversational style throughout the User Document. Using a conversational style, as if you were talking to your Reader, will make the writing easier (we will see that later) and the Reader more comfortable with your Document. So now you have an idea of what your document will contain. It’s now time to get some writing tools and begin to create your User Document.
|
(c) 2006 Igetitnow! Training, Inc.