The Structure of Your User Document

 

The Structure of Your User Document1

Table of Contents for this Reading. 1

Overview.. 1

Sections of Your User Document2

Your Document’s General Sections In Greater Detail:3

Cover or Splash Page. 3

"Read This First" Section. 4

If You Are…Then Read this…... 5

User Document Overview.. 5

Educational Material6

Preparing to Use The Product6

Using Your Product7

Products with A Continuum of User Skills and Needs. 8

Products with Different User Populations. 9

Care, Maintenance and Storage. 9

Additional Information. 9

Warranty or Guarantee Information. 10

In this Course You Will Write Your Document Based Upon these Guidelines:10

Some Modifications to these Section Types. 11

Almost Tutorial Style. 11

Moving On….12

 

 

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. 

Information that you feel should be in the document -- but must be excluded because of size restrictions -- could be placed on your company's website, with a reference on the product or the document to the Web address of that website.  This is a start on making your product an Internet Supported Product (See our Glossary).

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

In this component of this Course we are describing the Sections of Your User Document.  As I just mentioned, the sections you actually include in your Course are based on the product and the size limitations of your document.

How your document looks is another matter.  Your final User Document may be

· A few lines on a package
· A single or a few sheets of printed material
· A 500 page manual, either printed or in electronic format
· Online, context sensitive help screens

In all cases, the User Document starts out with the components and analysis that we will do in this Course.  Your layout artist will create the final design of the document.  However as we will discuss in the Access section of this Course, you should exercise some control over the final layout.  Your control will be concerned with making your User Document easy to use.

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)
Table of Contents
Copyright, trademark and patent information

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:
Preparing to Use The Product

        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 Page

A 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
I’ll say it many times in this Course: all modern products should be Internet Supported Products

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). 

When you provide information to the User, make sure that the information is of a form that the User understands.  I, as a User of the watch, understand “DataMaster 150.” I do not understand “Acme Module No. 1477.”

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" Section

In 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]
This can point to a troubleshooting section of the document, as well as give the Internet Address if the product is an Internet Supported 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 Material

Preparing to Use The Product

This 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.

That's fine, provided you have stated -- prominently and early in your User Document -- where to find this "Preparing to Use the Product" information.  Don't just stick this section in the Appendix and force the Users to search for it.  (I am not a fan of “Treasure Hunts” in a User Document; I don’t think that the Readers want to hunt for the material they need in your document.)

One product I ran into (by Acme, of Course) included the “set up” information in their “using the product “ section.  This is a mistake, as a User with a new product often realizes that there must be some form of set up, and looks for such a section in the 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.) 

This was a terrible waste of advertising real estate.  The box should describe the benefits of the shoe.  If the guarantee were special, then it could be listed with the benefits of buying the shoe.

Using Your Product

Here 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. 

1.  If your product has a feature, and you do not tell anyone about the feature or how to use that feature, then why was the feature included in the design of the product?

2.  (This is related to Access to the information in your User Document.)  If you write about something in your User Document, but the Reader cannot find it, then why did you bother writing it in the first place?  (That's why we spend a large amount of time in this Course improving the Access to the information in your User Document.)

 

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. 

Do not spend any time worrying whether something should be listed as a Basic or more Advanced feature.  Just assign them as you feel is OK.

Products with A Continuum of User Skills and Needs

Basic Operations

For 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 Populations

We 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 Storage

O     Care, Maintenance, Storage, Transport

O     Disposal of Byproducts

O     Disposal of the Product
Uninstalling the product (if it’s a software product)

Additional Information

O     Internet Supported Product
All modern products should be supported by (non-marketing) Web pages.  Minimally, a User should be able to read and/or download the User Document from these pages.

O     Appendices  (referenced within the document itself)

O   All messages and their explanation (including menus & screens, beeps and lights)

O   Troubleshooting

O   Adjusting Parameters
This describes every parameter of the product (especially software products) that is adjustable by the User.  This section may also describe the values of some constants (e.g. locations, etc.)

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. 
Even if you choose not to include the Appendices in the User Document, they can be valuable resources to you, the writer, and to your Readers if your product is an Internet Supported Product, with the Appendix information posted on the Web page.

 

Warranty or Guarantee Information

The 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
THIS is very important!  I stress in this Course that you must design and write the User Document based on the User, and what he/she (must/should/can) know about your product.  This makes for a User-Centered Document.  The opposite of a User-Centered Document is a Product-Centered Document, where you describe things from the product's point of view, and leave the User to figure out things for himself/herself.  A reference manual is an example of a Product-Centered Document.  Reference manuals can be converted to User-Centered Documents relatively easily as I describe later in this Course.

O     Written based on the Skills, Attitude, Knowledge, and Experience of the Users

O     Easy to Find the Information in It
Use titles and headings that are meaningful to the User (not the technical names of the product's components and features)
Provide effective access to all the material in the document

O     Easy to Read
Use of white space, separators

O     Easy to Follow Steps
Good overviews and check lists

O     Easy to Understand
Your clear, professionally edited and proofread text

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.

 

 

 


Resources for Writing Great User Documents: Home

(c) 2006 Igetitnow! Training, Inc.