How to Create Great User Documentation: A Hands-On Course
Course Syllabus

Disclaimer:  You and your Organization (Company, Group, Division) are totally and solely responsible for what you write, how you present that information and what you leave out of your User Document.

Make sure that your User Document clearly shows all necessary warnings, trademarks, copyright notification, and other legal information that is required by law, your industry and custom.  Check this information with your legal department or lawyers.

Neither Igetitnow! Training, Inc., or its authors or distributors or employees assume any responsibility or liability for your writing.

Please see our complete Disclaimer.

Back to the GreatUserDocs Home Page

Download the full Course (free, no-strings-attached) here.

Using This Material

You take this Course using your Internet Browser.  There are many activities in taking this Course.  They all lead to the successful completion of the User Document you have to create.

This is the main page of your Course.  Go through the all of the sections of the Course in the order that they are presented. 

O     Click on the items indicated "Listen:" to hear the audio presentation.  I have eliminated the links for this sample page.  Listen: Test.mp3

O     Click on the items indicated with "Read:" to read the printed material of the Course.
    You see a Reading in your Internet Browser's window.
 When you have finished the Reading, use your Internet Browser's [BACK] button to continue.  I have eliminated most of the links from this page (if I did not, I would be giving away all of the Course material).

O     Learn: Items with this label are for you to start learning in your "spare time."  You will need the knowledge and skills later on in the Course.

O     Get: Send out requests for this information now.

O     Do It: Do the activities you are asked to do in the Course.  These are the Steps you will take to complete your User Document.

Course Resources


Glossary

Rules and Tips

Writing Notation

Bibliography

Course Flowchart (In the Course, students can click on items in the Flowchart for an explanation.  This is an example of a Visual Index.)

For Help With this Course's Topics see our Course Support & Contact Page.
 

TIP:  A good way to read nonfiction materials is to look over the Table of Contents first.  This way you will have a good idea of what the material is about. 

I provide a Table of Contents for each Reading in this Course.  You can click on an item in a Table of Contents and you will be taken to the appropriate place in the Reading.

 

How to Create Great User Documentation: A Hands-On Course Course Topics and Overview.. 1

Course Resources. 1

Table of Contents. 1

Introduction. 5

Welcome to the Course. 5

About User Documentation. 6

Goals of Your User Document6

What We’ll Do in this Course. 7

Goals of this Course. 7

About YOU, the Person Taking this Course. 7

This Course is for You if…... 7

You, Now.. 8

You, When You Have Completed This Course. 8

About Me, Your Instructor8

The Acme Corporation. 8

Your Ongoing Course Assignments. 9

1.  Read Anything Professionally Written. 9

2.  Read User Documentation. 9

2a.  Read This Specific Piece of User Documentation. 10

Your "Case Study"11

1.  If You Are Now Writing or Starting to Write a User Document11

2.  If You Are Not Now Writing a User Document (and don't have one planned)11

Preparing to Create Your User Document12

How You Will Write Your User Document12

First Things to Do. 12

Document Specifications. 13

The Structure of Your User Document14

Background Material: Things to Keep in Mind. 14

Documentation Project Management15

Do It: Request “Legal” Information for Your Document15

Where You Are Now.. 16

What You Should Have Completed or Are Working On. 16

You Should. 16

Writing Your User Document16

General Writing Overview.. 17

Your Writing Tools. 17

Writing The Educational Part of Your Document17

Generating Your User Document Outline. 17

User Task Analysis. 18

User-Product Life Cycle (U-PLC)19

High Level User Document Outline. 19

Getting & Saving the User Document Outline File. 19

Modifying the User Document Outline. 21

Filling In the User Document Outline. 21

Additional Information. 21

Components. 23

Do It: The "Preparing to Use the Product" Section. 23

Do It: Product Startup and Shut Down. 23

Do It: Generating the "Using the Product" Topic List24

Do It: Care, Maintenance, Storage and Disposal of Your Product24

If You Are Having Trouble Generating Topics. 24

Optional Reading:  Organizing the Topic Lists. 24

Do It: Checking the Topic Lists. 24

Where You Are Now.. 24

Do It: Internally Publish and Get Approval for the Outline. 24

Writing the Components of Your Document25

Review.. 25

Do It:   Choose a Component to write about.26

Do It:  Analyze the Component and Extend Its Outline. 27

Do It:  Write About the Component27

Do It: Submit Graphics to the Artist for First Draft27

Do It: Review and Revise Your Writing. 27

Do It: Improve Access to the Component’s Information. 27

Do It: Test the Component 1: Preliminary Testing. 28

Do It:  Publish the Component for your Components Readers. 28

Do It: Testing the Component 2: More Formal Testing. 28

Do It: Prepare the Component for the Editor28

Do It: Send the Component to the Editor28

Do It: Repair it Based on the Editor’s Work...Then back to the Editor28

Do It: Add Graphics to the Component28

Publish the (close to Final) Component for Your Components Readers. 29

Evaluate/Modify Your Writing Techniques. 29

Many Steps:  Perform the Component Steps for all Components of Your Document29

Do It: Put the Components Together: High Level Topics Overviews. 29

Writing Your Document's Overview.. 29

"Read This First" Section. 30

The "If You Are…Then Read This…" Section. 30

Completing the Document30

Do It:  Resolve any Remaining Unknowns. 30

Do It: Add Appendices to Your Document31

If you are including a glossary in your User Document31

Provide Excellent Access to Your Information. 31

Preparing to Publish Your User Document32

Do It:  Assemble the Complete Document from its Components. 32

Do It:  Format the Pages so they Match the Publication Medium.. 32

If You Are Publishing your Document as an AcrobatÔ .pdf32

Do It: Index Your Document33

Do It: Final Document Testing. 33

Do It: Pre-Publication Review.. 34

Do It: Publish the Document35

Do It:  Support the Document35

Course Review & Next Steps. 36

Did This Course Cover Everything You Need?. 36

Your Next Steps. 36

Appendix A: Improving Existing Documentation. 36

Appendix B: Miscellaneous Topics. 36

Appendix C:  Some Examples. 36

Automobile Cruise Control36

 

 

 

Using These Resources

 

I recommend that in taking this Course you do the following:

1.      Print out the page that you are now reading (use your web Browser's Print function).

2.      Look the printed page over to get a feel for how the Course will progress.
Listen to my overview of the Course while you read over the printout

3.      Do what it says to do in each section of the Course:
·  Listen,
·  Read, and
·  Do as you are instructed

4.      When you have completed a section, write the date that you completed the section on your printed copy of this page.  This is so you can check for updates to the Course. See our Course Support & Contact Page.

 

Internet Links in this Course.  I have included a number of links to internet websites to add to the material in this Course.  Unfortunately, websites come and go, even ones maintained by governments and universities.  I periodically go through the Course to check the websites, and add new ones when some of the existing ones vanish. 

If I miss some invalid website reference, then please forgive me.  I recommend that you do a search on the Internet or Wikipedia for the topic.  (I like Wikipedia.)

 

Read: About This Course

 

Danger! I repeat things.  As you go through this Course you may find things that you read in other parts of the Course.  I repeat things.  I do this because I feel that the material bears repeating (because it fits in several places in the Course).  I prefer to minimize your bouncing around the Course with links so I repeat things.  (That’s the third time I said, “I repeat things.”)  I hope that this repetition does not bother you too much.

Welcome to the Course

Listen: Welcome.mp3

Hi:

My name is Barry Millman, the developer of this Course, and your instructor.

I would like to welcome you to this hands-on, computer-based Course that will guide you in creating great User Documentation.  In this first part of the Course we will talk about User Documentation in general, about the Course itself, and about you and me.  After that, we will get into the actual creation of your User Documentation.

          This Course is concerned with the Content of your User Document:

O     How to design the information in your User Document

O     Write the Content, and

O     Make that Content Accessible to your Reader

 

This Course does not deal with any piece of software or publishing technique.

               I know that this Course will be of great assistance in helping you produce the best possible User Documentation.

          I trust that we will have a great learning and writing adventure together,

 

Barry Millman

It is noble to help others to get their good works done.     Barry Millman

About User Documentation

What Users want from good User Documentation:

O     How to use the Product

O     How to fix things that go wrong

O     How to be protected:
   Protect their warrantee
   Protect themselves

O     To learn about the product

 

Read: About User Documentation

Goals of Your User Document

Your User Document will provide the information that your User needs to become effective (capable of doing what he/she needs to do), and comfortable using the product as quickly and easily as possible.

The information in your User Document will be clear, complete and understandable by the Reader.  Your information must be accessible when it is needed, and easily skipped when not needed. 

What We’ll Do in this Course

Learn some powerful writing techniques (but very little – almost no – grammar; we will rely on an outside Editor to worry about grammar.)

Understand your Reader, the product, and the role of the document

Actually write the documentation you have been assigned (at your work) to write.

Essentially you will

O     Learn how to create effective User documentation.  (That's User documentation that helps the User get on with his/her work.)

O     Create the User Documentation that you have to for your real-life (job) situation.  You will create effective Documentation efficiently, while learning the underlying principles of great User Documentation.

I want to discuss these topics in greater detail in the next few sections.

Read: What This Course Is and Is Not

Goals of this Course

Listen: AboutThisCourse.mp3

This is the ultimate hands-on Course.  In it you will create the documentation that you have to write for your real-life work.  (If you do not have such a document to create, you can practice on a Case Study, which I will describe later.)

Creating great User Documentation.  Great documentation has the information that the User needs, presented in a way that the User can find and understand it.  Great User Documentation helps your User to be comfortable with your product.  "Comfortable" means not having to guess about safe, proper usage of the product.

Creating effective User Documentation easily.  I have broken the “art” of writing User Documentation into a series of steps.  So the “art” now becomes a “science.”  This Course clearly explains the background and the skills needed for you to perform each step.  You perform the steps (some are repetitive, for each part of your User Document), and produce an excellent User Document.  

This Course is practical.  It is firmly grounded in reality.  It works!

 

About YOU, the Person Taking this Course

Listen: AboutYou.mp3

This Course is for You if…

You have been assigned to write or improve the User Documentation (or part of it) for a product.

You can think clearly, and understand the idea of an outline (a listing of topics and subtopics under them).  Later in the Course I'll present some links to Internet sites where you can brush up your outlining skills.  We will not be concerned with formal outlining skills like you were forced to use in school; so don't worry.

You can (if nobody is around) verbally (out loud) describe how to use your product.

You can create effective User Documentation even though your name is not Shakespeare, Wordsworth, Tagore, or Browning.  You are not expected to write elegant text.  Your goals will be clarity and completeness.

I have to make some assumptions about you.  That's what I am doing in this section of the Course.  I will also describe how you will change when you have completed this Course.

You, Now

Here are the assumptions that I am making about you.

Read: Where I Assume You Are Now

You, When You Have Completed This Course

These are the skills, attitude, knowledge and experience (completed items) when you finish this Course.

Read: Where You Will Be When You Finish this Course

You'll be well on your way to completing the User Document you have to write for your real-life work!

Note:  In this Course, whenever I use the terms "Your Document" or "Your Documentation" I will be referring to the actual documentation you have to write for your real-life (job) work, or the one you have chosen for your Case Study, described later in this Course.

Hopefully you will be more critical of the User Documentation that you find all around you.  You will seek--and find-- ways to improve that documentation. 

The Acme Corporation

Listen: Acme.mp3

The Acme Corporation (a fictional company) creates many of the products that we use.  Unfortunately they make many documentation blunders.  We have all been subject to them, and they will form many of the examples in this Course.

Read: The Acme International Products Corporation

Your Ongoing Course Assignments 

1.  Read Anything Professionally Written

You should be reading newspapers, magazine articles, books, whatever.  While not all paid authors are necessarily good, you should remember that:

O     They are getting paid to write (so someone likes their writing)

O     Their work is edited (so it has been gone over by a professional editor)

 

Try to see how the authors made their writing clear, understandable and to the point.  Look at the wording they use.  If you find some words that you do not understand, then imagine how your Readers will feel if you use words that they do not understand (without your explaining them).

Beware:  There are many mistakes in professionally written materials.  So just because you read something in a newspaper, magazine, book, (on line) or a User Document do not think that you are looking at perfection.  As we go through this Course I will point out some of the writing problems I have found with the writing of various professionals.

I also want to comment about "perfection."  When we write, when we do anything, our goal should be improvement, not perfection.  Having perfection as a goal will almost guarantee that you will not finish your project.  So let's drop "perfection" from your list of goals for your writing project.  "Really, really good" is an excellent goal.

Don't Worry About It.  Every writer worries about creating the perfect document.  It won't happen, there will always be some small errors.  Thus you should not let the fear of not reaching perfection freeze you. Even professional journal articles have errors. 

In a Harvard Business Review article (March, 2005) entitled "Lean Consumption" by Womack and Jones, page 61 has two errors that any editor should have found.  In both cases the authors, editors, proofReaders, and publisher permitted the word "insuring" to be used when the proper word was "ensuring."  "Insure" is what you do to avoid large monetary loss. "Ensure" means to "make sure of."  Even with this oversight, the article was clear and informative.  (A later section of this Course presents "spelling errors" that your spell checker won't catch.)

The lesson here is to make sure (ensure) that you write clearly and completely; don't try to make everything perfect.

2.  Read User Documentation

While you are working on anything related to User Documentation, I want you to find and read any User Documentation for any products that you can.  Read the documentation for all of your home appliances, for your computer, for all of the software you have. 

Be critical of the documentation.  Ask yourself the following questions about the User Documentation you find (and read):

O     Who are the Readers of the User Documentation (and the Users of the product)?

O     Is the material complete?

O     Does it meet the needs of the Users of the products?

O     Can the Readers understand the document?

O     Is it easy to find things in the document?

O     Do you like the layout of the document?

 

Try to think about ways to improve the documentation that you read.  The goal of great User Documentation is that the documentation should make the User more effective with the product.

You should consider incorporating the good ideas you find in the User Documentation you read. For example, you might like the layout or the style of the documentation.  It's quite fine to copy those aspects of whatever you read.  However, you should never plagiarize (copy directly, without getting approval or giving credit) material from someone else's work.  

Become a critic of User Documentation.  Apply what you find to the documentation that you have to write.

2a.  Read This Specific Piece of User Documentation

The technique that you will use to write the material for your User Document involves sending copies of your writing to others on the Product project team (who we will call the "Components Readers") for their comments.  The most efficient way for this to work is if you all have the same word processing software; this way you can e-mail them a copy of your writing, they can make comments on the electronic version, and e-mail it back to you.  You will then be able to read their comments and changes on the electronic document, and either accept or reject the changes.

The problem is that your Components Readers probably will not know how to use this feature of the word processor.  You might have to explain this feature to them. 
If you choose to just tell them where to find the information in the word processor's User Document, then you are letting your "Users" figure out how to do this on their own.  This is not a good attitude for you, as a User Document writer, to have.

This multiple author capability might be called by your word processor "multiple authors", "revisions", "versions" or whatever.

Your task is to do the following:

1.  Find the information in the word processor 's User Document that describes this multiple authoring capability.  Be aware: How difficult was it to find this information in the word processor 's User Document?

2.  Read the word processor 's User Documentation about the multiple authors feature.  Be aware: How well does it explain about the feature and how to use it?  Does the User Document present any tips, traps or troubleshooting for the multiple authors feature.  For example, you will be using the multiple authors feature to deal with comments from many Components Readers.  Does the User Document tell you how to do this?

2a.  Use the word processor 's User Documentation to guide you in using the multiple author feature.  Be aware: Does the documentation match the way the word processor works?  Does the documentation leave out steps or other information you need to use the feature? 

3.  Think about how the word processor 's User Documentation about the multiple authors feature could be improved.  (Remember this is probably an expensive piece of software, created and User Documented by a large company.  How did they do?)

4.  Think about you would rewrite the User Documentation for word processor 's multiple authors feature. 

 

Your "Case Study"

I have provided two types of Case Study for this Course.  Your choice of Case Study will depend on whether or not you have a User Document that you have to write or are currently trying to write…

1.  If You Are Now Writing or Starting to Write a User Document

Use your actual documentation project as your case study.  This Course will guide you through to the successful creation of an effective User Document.

2.  If You Are Not Now Writing a User Document (and don't have one planned)

Create and evaluate your own Case study. Here are the steps:

1.__ Pick any product in your world that you have the User Documentation for -- but don't read the documentation now.  If you read it a while ago, then that's OK.  Pretend you haven't read it.

2.__ Use that product as your case study

3.__ When you are done creating the User Document for that product based on the techniques in this Course, compare the User Document that you created with the one that came with the product.  I trust that with the guidance of this Course, your User Document will be better than the one that came with the product.

"The greatest mistake you can make in life is to be continually fearing that you will make one."       Elbert Hubbard

 

How You Will Write Your User Document

Listen: HowYouWillWrite.mp3

In this Course (and hopefully in all of your writing of User Documents) we will use an iterative, interactive approach to writing.  Rather than create an outline and then go off and write, we will do the following:

1.  Create the high-level Outline for the User Document.  Don't stop here!  Even if you have only part of the overall Outline, you can begin to work on the Components (see Glossary), while your Components Readers (see Glossary) are reviewing the Outline (item 4., below).

2.  Make the Outline available to your Components Readers (described in the readings for this section of the Course).

3.  Revise the Outline based on your Components Readers’ comments and suggestions

4.  Select a chunk (which we call a Component) of the Outline and write a draft of that Component. 

5.  Let the draft sit while you return to Step 4 for another Component. 

6.  Review and Revise the draft of the Component that has been sitting for a while.

7.  Make the Component available to your Components Readers. Encourage the Components Readers' comments, suggestions and corrections

8.  Revise the Component, as per the feedback from step 7; if there is none, then you are ready to send the Component to your Editor. When it returns from the Editor, deal with changes that the Editor suggested.  Publish the revised Component as described in Step 7.

9.  Get approval of the completed Component.

Repeat steps 4 through 9 until the User Document (or your portion of it) is completed.  Publish the User Document for the Users of the Product.

This is explained in greater detail in these readings:

Read: How You Will Write Your User Document

The next Reading tells you how to set up your Internal Publication Medium and how to publish the information to your Components Readers.

Read: Internal Document Publication.  After reading this, set up your Internal Publication Medium.

First Things to Do

Listen: FirstThingsToDo.mp3

I assume that you are working on a tight schedule; that you have documentation that you have to write for your work.  There is no loss if my assumption is wrong…the result of this assumption is that I want you to complete your documentation as quickly as possible.  That is one of the goals of this Course. 

Here are some things to do, and some things to start and continue doing as you create your User Document. 

 

We will work on the User Document Specifications in greater detail later.  In this section you should begin gathering the information about the product, Users, and the User Document that you will be writing.

Before you do anything else, set up a procedure and place to document the documentation project.  This will be of value to you now, and in the future, when someone has to maintain the User Document. 

Read: Document Your Documentation 

Now you can look into the first things to do.

Read:  The FIRST Things You Need to Do 

This next reading presents the resources you need to create your Great User Document.

Read: Before You Write

The next Reading discusses interviewing and other fact-gathering about the Product.  The motto is "Be Prepared."  That is, know as much background  information as you can before going into an interview with your subject matter experts.

Read: Gathering Information

This optional Reading just lists some points of information to gather and things to feed back.. 

Look Over: Questions to Ask/Things to Tell

Document Specifications

Listen: DocSpecs.mp3

The Document Specifications will guide you in both the writing and revising of your document.  In addition, the Document Specifications will form most of the Overview Section of your User Document.

Do not be tempted to say something like "I know what the specifications are" and thus skip this section.  These specifications are important for your writing project.

Read: Document Requirements

Essentially there are three components to the Document Specifications.  They deal with

1.      The Four Dimensions of your Reader/User
Listen: AboutUser.mp3
Read: Describe Your Reader
Create a Persona -- a "Typical User" who will help you with your writing.
   Read:  Create a Persona

2.      The Product
Read: Describe the Product

3.      The Goals and Mechanics of the User Document Itself
Read: List the Scope and Purpose of the Document
This Reading describes the various types of User Documentation that you might choose to produce for your product.
Read: Types of User Documentation

 

Record the information you gather:

1.      Add all of the information that you gather creating the Document Specifications to your User Document Specifications document.  We set this up earlier in Document Your Documentation .

2.      Publish the User Document Specifications document on your Internal Publication Medium, and e-mail it to all those involved with the product (your Components Readers).  We discussed this Internal Publication Medium and the Components Readers in Internal Document Publication.

3.      Ask for the Components Readers' comments, suggestions, and additions. 

4.      Evaluate the responses you get from your Components Readers. 

5.      Modify the User Document Specifications document and re-publish it (internally) and e-mail it to the Components Readers.

The Structure of Your User Document

Listen: DocStructure.mp3

This Reading describes the generic layout of your User Document, that you will produce in this Course.

Read: The Structure of Your User Document 

Your User Document might not have all of these sections, and some sections may be larger than we describe in the Course.  Base the decisions about the structure of your document on your product. Don't worry about space and size of the document.  Buried in this Course is a tip on how to put a many-page document on a box of toothpicks.

I believe that Overviews are necessary to your Reader understand the material that is to follow.  Thus I hope that you take the advice of this reading and include Overviews everywhere that you can.

Listen:  Overviews.mp3

Read: About Overviews

 

Background Material: Things to Keep in Mind

Listen: KeepInMind.mp3

This section is aimed at getting your attitude aligned with the goals of a good User Document.  Some of these readings are philosophical in nature.  Some are practical. 

Later, when you begin to work on your first draft, I do not want you to return to this information to guide your writing.  That would slow down your writing of the first draft.  Just keep this information in mind when you are writing.  Let it soak in, and then forget about it.

These are topics to keep in mind throughout this project.

Read: REALITY: Ignore it at your own Peril

Read: General Guidelines

Read:  Things to Keep in Mind

The object of teaching someone is to enable him/her to get along without the teacher.      Elbert Hubbard (paraphrased)

Documentation Project Management

Please understand that I am a "do-er" and not a manager.  I will assume that a manager who is taking this Course will know something about the art and skill of managing.  Thus I will say very little about actual documentation project management.

Since I advocate that you write the document in chunks (and these get passed around for comments from your Components Readers), and the chunks are small, I strongly suggest that only one author works on any chunk.  This reduces the need for any complex revision control system.  The version (or revision) control in your word processor software should be all you need.

Do it:  Learn about how your word processor handles work by multiple authors (your word processor's Documentation may call this "revisions" or "version control").

Having said that, I will add that I have structured your work in this Course so that you will be able to complete your documentation task in the shortest possible time.

Read: Document Approval

Read: Documentation Project Management

This next reading describes what to do when you are rushed to produce the User Document.  Read: Time, Scheduling and Your Work on the Document: Working Fast! 
Read: Creating Quick and Dirty User Documentation

Do It: Request “Legal” Information for Your Document

Your Primary Concern when producing User Documentation is to protect your organization (that is, your company).  You must include the correct legal information in your User Document so that your company is protected.  For this reason you should have your company’s legal department examine the “Legal” Information in your User Document. 

This review by the legal department should include the entire document; minimally the legal department must review the Overview to the User Document. 

Disclaimer, again:  You and your organization are totally responsible for what you include in the User Documentation, how you present that information and what you leave out. 

Neither Igetitnow! Training, Inc., or its authors or distributors or employees assume any responsibility or liability for your writing.

Listen: Legal.mp3

Read: Get Legal Information

What You Should Have Completed or Are Working On

O     You are reading User Documentation for the products in your life, and learning from it

O     Documentation Project or Case Study selected

O     Computer folder for your writing and notes

O     E-mail folder set up to store all correspondence for the Documentation project

O     You have set up your Internal Publication Medium

O     You are documenting your User Documentation

O   You are keeping track of the personnel on the Product and Documentation project

O     You are working on your Document requirements

O   You are learning about the Product, Readers/Users, and the User Document Requirements

O     You should be on the way towards hiring an editor

O     You should have a Style Manual selected

O     You have requested the Legal Information you will need for the User Document

You Should

O     Know about the benefits of good User Documentation

O     Be learning proper use of your writing tools (we'll cover this later in greater depth)

O     Know about reality regarding the Product and the User Document

O     Know (generally) the procedure for producing your User Document and how it will look

 

Now we will get on to the writing of your User Document.

You will have many things going on at the same time as you write your User Document.

General Writing Overview

This information will help you feel better about the writing process.

Listen: WritingBackground.mp3

Read: Writing: Overview & Background

 

Your Writing Tools

Your tools include the people you work with, as well as your "word processor" and its capabilities.

Listen: WritingTools.mp3

Read: Your Writing Tools

Read: Meditation

Read: Writing Notation 

Read: New Technologies In Content Management

Listen: WritingEducational.mp3

This part of the User Document tells the Reader how to use your product.

The Educational Part of your User Document includes:

O     Product Setup

O     Starting and Shutting Down the Product

O     Using the Product
Grouped based on the Users’ skills and/or needs

O     Care & Maintenance of the Product

O     Disposal of the Product

 

For most products, this is the largest component of the User Document.  It tells the Reader how to use the product. 

Perhaps the only product where the Educational Part of the document is not the biggest is for ladders.  Ladders have no User Documentation, but do have a lot of "Read This First" material.  The safety warnings about ladders make up much of the "Read This First" section.  Most of this information is "published" in the form of labels on the ladders themselves.

Aside: The Place for User Documentation.  The ideal place for User Documentation is right with the product itself.  Thus someone using the product can get the assistance he/she needs without having to first search for the Documentation.  Software products achieve this with on-line or any directly viewable User Documentation.  It would be nice if physical products at least had a pocket to hold its User Documentation.

Generating Your User Document Outline

Listen: GenOutline.mp3

The first step in creating the educational portion of your User Document is to generate a list of the topics that your User Document will present to the Reader.  That's what we'll do in this section of the Course.

As you can see from the following Course Steps, we have broken down the topics into tasks that your User must complete in order to be successful with your product.

If you are having problems generating topics in the next few sections of the Course, there is a section entitled "If You Are Having Trouble Generating Topics " 

User Task Analysis

Earlier, we completed our document specifications.  These tell us about

O     The Product

O     The User

O     The goals (scope) of the Document you are writing

 

The User uses your product to meet his/her needs.  The User meets his/her needs by performing tasks with your product. So our next step is to analyze the tasks that the User performs with your product.   This task orientation will form the basis of the educational component of the User Document.

We use the document specifications to generate a list of tasks that our Users might do with the product. 

There are three general kinds of User Tasks: 

O     Must Do in order to get the product to work.
These include preparing to use the product, maintenance, storage, startup, and shut down.

O     Wants (or Needs) to Do with the Product.
These are the actual tasks that the User performs with your product to meet his/her goals.
For ease in generating the topics, these are broken down in either of two ways:
1.   Basic (more commonly used) and Advanced (specialized or less frequently used, "fancier") Tasks
2.  By type of User and their use of the Product 

O     Cannot Do with the Product.
This information in this category is not to be placed in a separate section of your User Document.  It may appear in the "Read This First" section, and should also appear in appropriate places throughout the Document (where a User might think of doing something they shouldn't or cannot do)

There are two situations dealing with what someone cannot do with a product. These are:

1.      What the User should not do with your product, usually for safety or product reliability reasons.

2.      What the User might want to do with your product (and is safe and logical) but cannot do.  The product does not have the capability to perform the desired actions directly.  This is a call for tips on how to perform these actions.

Read: Should Not Do & Can Not Do

User-Product Life Cycle (U-PLC)

Normally when we think of a Product Life Cycle, we think in terms of the development and production of the Product itself.  However, I believe that we should think of the User-Product Life Cycle (U-PLC). 

The User-Product Life Cycle refers to the range of global interactions between the User and the Product itself.  Do not confuse this global User-Product interaction with the interaction between the User and the Product when the User is actually using the product.  As you will see below, "Use the Product" is one piece in the U-PLC.

Here are the parts of the U-PLC (after the User as acquired the Product):

O     Transport the Product to its working location

O     Unpack the Product

O     Set up the Product

O     Use the Product

O     Maintain the Product

O     Move the Product
For a computer software program, how would the User move the program and its data to another computer; computer Users often upgrade their computer hardware.
For a physical product, how would the User move the Product to another location?
I did not create an extra item in the User Document Outline for this step.  You can choose to create a "Move the Product" Outline item, or put "Move the Product" as a topic in the Maintenance Outline item.

O     Discard the Product or its By-Products

 

As you generate topics make sure that you keep the U-PLC in mind.  Ensure that you include topics in your User Document Outline to assist your User in all phases of the U-PLC.  (This Course has most of these parts of the U-PLC in its Outline.)

High Level User Document Outline

You will create an overall outline for your User Document.  I recommend that for your highest level outline that you follow the structure that I present in "What Your Document will Look Like." 

I have created a Rich Text Format (rtf) copy of this high level outline. Most word processors will open an rtf file, so you can open it and use it for your high level outline.

Getting & Saving the User Document Outline File

Listen: HLOutline.mp3

If you click on Outline File: High Level Outline Document.rtf it should open in your word processor.  (If your word processor will not open the file, then go to the directory (folder) on your computer that you copied this Course.  The file has the name shown on the link above. Copy the file to the directory where you will be storing your word processing files for your User Document.)

Back Up Your Work with Dated Backups.  I recommend that you back up your work frequently.  However, do not simply store the entire folder on a device separate from your computer (such as a Compact Disk, CD).  Instead do this:
1.  Create folders (subdirectories) on the CD for the date of the backup; that is, name each folder with a date.  The date (folder or  subdirectory name) should be of the form YYYY-MM-DD, as 2006-04-10.
2.  Then copy all the current files for your User Document into that folder.

The benefit of this scheme is that you can recover a previous version of your writing if you change your mind after you have edited it.  It makes you less fearful of making changes to your writing; you will know that you can always go back to a previous version.  This is an important stress-reducing technique in any work on a computer.

Save the High Level Outline file that you opened. 

O     Save it to the folder or subdirectory where you are storing your working documents for this User Documentation project.

O     Save it in your word processor’s native format
For example, if you are using Microsoft Word, then save it as a Word document. You will probably do this by using your word processor’s "Save As…" menu.

 

I recommend that you keep all of the word processing files for your User Document in the folder or subdirectory that you created earlier in the Course.  Use this folder or subdirectory to store only files for this User Document.

 

We will call this the (High Level) User Document Outline.  You will be adding to this outline file as you work through the Course.

 

Some topics in the User Document Outline I present might not be relevant to your Product.  I recommend that for the time being, you leave them in. Perhaps in your investigation and brainstorming of ideas (topics) you might need these not-immediately-apparently-relevant topics. 

If, after your analysis, you find that certain topics are not relevant to your product, then remove them from the outline.  It looks silly (overly formal, overly mechanical, overly templated) to say something like "Maintenance: This area is blank."  In this example, just leave the " Maintenance " portion out of the outline completely.

 

Modifying the User Document Outline

You may rename items on that outline, as you desire. Based on the structure of the User Document.  For example, in the "Using the Product" section of the Outline I named the sections "Basic" and "Advanced" usage.  This might not be appropriate for your product.

O     You may change the names of the "Basic" and "Advanced" features outline topics to something more relevant.  I used those names to guide you.

O     You may divide the structure by type of User.  Thus you may replace Basic" and "Advanced" with the type of User, for example "Managers" and "Employees.

 

As we progress through the Course, you will fill in the outline by adding high-level (major) topics to that outline.  When you select a portion (which we will call a Component) of the outline to write about you will extend the outline for that Component to include its lower-level topics (headings).  So keep this high-level outline just that, a high-level outline.

Don’t Wait!  Your tendency might be to wait until the High Level User Document Outline is complete and approved before going on to writing.  That is incorrect! 

As soon as you know some of the topics in the Outline that will be approved (or have a high probability of approval), work on those topics in parallel with the completion and approval of the High Level User Document Outline.

Filling In the User Document Outline

 

In the next four Steps (which you can work on in any order) you will begin to fill in (add topics to) the User Document Outline. 

We will fill in what we may call the higher-level topics.  That is, we do not want to go down to the low level (fine detail) topics that will be in any Component we will be writing.  We will add the lower-level topics as we extend the outline into the Component, later.  However, be flexible!  If you think of some great low-level topics for your outline, then put them in. 

Read: About Topics and Generating Topics

Additional Information

Listen: AdditionalInformation.mp3

As you work on the User Document, you should have some ideas for additional information that may be of benefit to the Reader.  There are two places for this information:

O     The first place is right with the topic that the additional information is directly related to.

O     The second are Appendices to the document.
If you put additional information in an Appendix, then make sure that you tell the Reader in the main body of the User Document where the additional information is located.  If the Reader does not know the information is available, or it is difficult to find, then the additional information is useless.  (Don’t let that additional information be useless!)

 

You may choose to repeat the information that you would embed in your document in the Appendices.  That is a logical way of doing things.

If you choose only to place some additional information in the Appendices, then indicate in the relevant main portions of the document that additional information is in an Appendix (and tell which Appendix).

 

The Appendices for your User Document should present Additional Information that you feel should be concentrated in one place in your User Document, or would disturb the flow of the User Document.  This Additional Information may include:

O     All product 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 (including a Bibliography, product Web site)

O     Glossary

 

For a good source of Additional Information in the form of Tips, contact your Subject Matter Experts, especially the developers of the Product.  Ask them to provide you with tips on better use and how to overcome shortcomings of the Product. 
Put those tips in the related places in your User Document.

 

As you write the document, add the information to the Appendices (this is especially true of the entries for the Glossary).

From Feature to Expensive Flaw.  My MP3 player has a battery-saving feature: when the battery is low, the backlight will not illuminate.  This not mentioned in the User Documentation for the device. 

Thus, as the User's first battery wears down, the backlight stops working.  To the User left in the dark (pardon the pun), this is a product failure
This failure leads to a frustrating and expensive call to Customer Service ("I need to return the player") or Technical Support ("It's broken.").

The writers should have included a simple statement in either the "Troubleshooting" or "Backlight" section of the User Document, mentioning this feature.  Adding the information would result in the reduction in frustration to the User and the reduction of expense to the Company.

TIP:  Ask your developers if there are any hidden features.  Document them!

Components

Later, you will select a topic or group of topics to write about in the User Document Outline. We will call these the Components of your User Document. (Ultimately, you will write about all of the topics that you are assigned by your boss, but you will work on the Components one at a time.)  Here’s an overview of how you will handle the writing of the Components.

O     Put each Component in a separate word processing file

O     Make a reference to the file name of that Component's word processing file in the appropriate place in the User Document Outline.
Use a link on the User Document Outline file just like I created links on the page that you are now reading; your word processing software will enable you to insert hyperlinks to the documents.  The purpose of the link is to enable your Components Readers and you to see how each Component fits into the structure of the User Document.  The outline provides the structure, and a click on the link provides the text.

O     Create an outline for that Component in its own word processing file.  Add the lower-level topics relevant to that Component in outline form.  I call this “extending the outline.”

O     Write, review, format and provide access to the information in that Component (it is still a draft)

O     Internally publish the Component to get feedback from the Components Readers in your organization. 

 

If in the next Steps you have trouble generating topics, please scroll down this page to the heading "If You Are Having Trouble Generating Topics."  There is information there to help you.

Do It: The "Preparing to Use the Product" Section

This deals with unpacking, setup, installation, and related topics.

Listen: PreparetoUseProduct.mp3

Read:  Preparing to Use The Product Section

Do It: Product Startup and Shut Down

This deals with the variety of ways to start up and how to safely shut down the product.

Listen: StartupShutdown.mp3

Read: Starting and Shutting Down the Product

Do It: Generating the "Using the Product" Topic List

Here we create the part of the User Document outline that deals with the actual usage of the product.

Listen: UseProdTopicList.mp3

Read: Generating the Topics for the “Using the Product” Sections of Your Document

Do It: Care, Maintenance, Storage and Disposal of Your Product

Read:  Care, Maintenance, Storage and Disposal

If You Are Having Trouble Generating Topics

Listen: TroubleGenTopics.mp3

Read: If You Are Having Trouble Generating the Topics

Read:  Fitting Important Topics That Might Not Fit

Optional Reading:  Organizing the Topic Lists       

If you followed our guidelines in generating topics then you can skip this, although there are some interesting concepts in this reading…

Read: Organize Your Topic List

Do It: Checking the Topic Lists

Consider this your first Usability Test of your document.  It is a general usability test, where you determine if the outline of your document meets the goals and purpose of your document for your intended Reader.       

Read: Check Your Category and Topic List

Where You Are Now

At this point you should have made significant additions to the High-Level User Document Outline.  These additions are the high-level topics relevant to your product.

Listen: ReviewAfterOutline.mp3

Do It: Internally Publish and Get Approval for the Outline

O     Publish the overall High-Level User Document Outline for your Components Readers.  We discussed this in Internal Document Publication. 
Tell them that you want them to review the outline and report missing topics or topics that seem out of order to them.
Tell them when you want their reply (a few days, depending upon how busy they are). 

O     Encourage your Components Readers' comments and suggestions. 

O     Modify your Outline based on their comments.

O     Publish the revised overall Outline.

O     Get Approval of the Outline

 

Do NOT wait until you are finished with the High-Level User Document Outline before going on to the next steps.  It might take a while to get the responses from your Components Readers.

Instead, continue on …

Writing the Components of Your Document

Listen: WriteComponents.mp3

We will now write the first draft (rough copy) of a Component in your outline.  Work on each Component (and related sub-sections) of your topic list separately.

As you complete a Component, you will submit the graphics for a first draft, and review and revise the Component.  Publish the Component as soon as possible in this series of steps (we discussed this earlier How You Will Write Your User Document) to the Components Readers of your document.  Encourage feedback.  Incorporate the feedback as you see fit.

Here is some background material to help you prepare for writing

Read: Write the Actual Topics of the Documentation

These next six readings describe various ways to present information in your User Document.

1.  Read: Narrative Style

2.  Read: Lists: An Effective Writing Style

3.  Read: Use Tables to Effectively Present Information

4.  Listen: StepByStep.mp3

Read: Creating Step-by-Step Documentation Components

5. Read: Question and Answer Format

6.  Sometimes you may most effectively present your information in a totally Graphic Component, with little -- if any -- text.  Read: The All-Graphic Component

Now you have some tools and understanding about writing.

I just want to present some reminders to make things go easier.

 Read: Prepare to Write!

So in practice, you will be working on the next series of Steps for each of the Components in your topic list.

Review

Here's what we've done so far:

O     You created a list of attributes (SAKE) of your Reader.
It could be just the "average person."

O     You have a list of the tasks that your Reader does with your product.
You know how the product affects the Reader.

O     You know the scope of the document you are writing.

O     You have created a User Document Outline of the topics in your User Document.

 

Generically, the User Document Outline might look like:

Topic1

          SubTopic 1

                   Sub-SubTopic 1.2

                   Sub-SubTopic 1.3

                   Sub-SubTopic 1.4

          SubTopic 2

          SubTopic 3

Topic2

etc…

For Wordwhacker's formatting section we might have:

Formatting

          Formatting Text

          Select Text

          Apply Formatting

          Undo and Other Tips

          Additional Information

          Formatting Paragraphs
                   etc…

          Formatting Pages

                   etc…

Now, we want to start working on a piece of that topic hierarchy, what we will call a Component.  

Our next step is to select a Component where you want to begin your writing. 

Do It:   Choose a Component to write about. 

At this point we are going to begin to work on the material for your User Document.  A Component is simply a chunk of the User Document that you choose to work on at this time.

Listen: ChooseAndAnalyzeComponent.mp3

Read: Selecting a Component

Do It:  Analyze the Component and Extend Its Outline

Now that you have chosen a Component to work on, and have created a word processing file for it, you will analyze the Component (a fancy way of saying “learn about it”), and extend its outline.  We will do that in this Step.

Read: Analyzing Your Component

Do It:  Write About the Component

You have chosen a Component to write about, and have organized the ideas into a Topic Template.  Now on to the "writing" of the first (rough!) draft.

Listen: WriteFirstDraft.mp3

Read: Do It: Write the First Draft of a Component

Learn:  About your word processor's grammar and readability checker.

Do your work with your whole heart, and you will succeed - there's so little competition.        Elbert Hubbard

Do It: Submit Graphics to the Artist for First Draft

As you have been writing the topic text (and even listing your writing ideas) you may have been making sketches to support your writing.  In order to keep the writing project moving at a good pace, submit your sketches (with any necessary explanation) to a Graphic Artist who will create rough drafts of the graphics for the User Document.  This way you and the artist will be working on the Component at the same time.

Read: Using Graphics: Pictures, Diagrams and Figures

Read: Do It: Submit Graphics to the Artist for First Draft

While the Graphic Artist is working on the graphics for a Component, you will be working on the next steps for that Component.

Do It: Review and Revise Your Writing 

The main work in your writing is actually in this Step.  Here you will review and revise your writing to make it as clear as possible.  Don't worry about grammar and final polishing; you will have an editor work on your writing, in a later Step.

Listen: ReviewAndRevise.mp3

TIP:  The more times you review and revise your Component (to practical limits based on deadlines) the better your Component will be.  As you continue through this Course you will return to review and revise your Component when you do other work on it.

Read: Concise Writing

Read: Revise Your Writing for Clarity and Completeness

Do It: Improve Access to the Component’s Information

This Step involves making things easier for the Reader to find information in the Component, as well as making the Component easier to read.  The topics in this Step include

O     Improving the access to the information in the Component,

O     General layout of the Component and

O     A bit on actual formatting of the text in the Component. I only have a few requirements related to formatting, which relate to making the text easier to read and removing ambiguity. 

Listen: ComponentAccess.mp3

Read: Component Information Access

Do It: Test the Component 1: Preliminary Testing

Here you will test the Component on yourself. 

Listen: TestComponent.mp3

Read: Test the Component

Do It:  Publish the Component for your Components Readers

It's now time to let your Components Readers review what you have written.  Remember, if you feel uncomfortable about this, you can send the Component to your editor for a pre-Internal Publication review.

Listen: InternalPublishComponent.mp3

Read: Let Your Components Readers Review the Component

Do It: Testing the Component 2: More Formal Testing

This deals with testing the Component on other people.  You might not have time to do this for all of the Components in the User Document.

Listen: ComponentFormalTesting.mp3

Read: Test The Component on Others: General Guidelines

Do It: Prepare the Component for the Editor

Read: Prepare the Material for the ProofReader/Editor

Do It: Send the Component to the Editor 

Read: Send the Component to the ProofReader/Editor

You should be working on another Component while your editor is working on your material.

Do It: Repair it Based on the Editor’s Work...Then back to the Editor 

Read: Repair the Component Based on the ProofReader/Editor’s Work

Do It: Add Graphics to the Component

Incorporate the graphics that your Graphic Artist has provided (in an earlier step) into your Component.   Remember, the graphics must relate to your text.  Graphics must make it easier for your Reader to understand what you are trying to say. 

You might wish to Re-read: Using Graphics: Pictures, Diagrams and Figures

Publish the (close to Final) Component for Your Components Readers

At this point you should submit the Component for approval.  Get the approval in writing.  The approved version should replace the last version on the Internal Publication Medium, and should be e-mailed to your Components Readers for final comments.

Get signoff (written approval) of the Component now!

Evaluate/Modify Your Writing Techniques

Here you can learn to improve your writing from the Iterative, Interactive Process we are using to create the User Document.

Listen: EvaluateYourWriting.mp3

Read:  Self Feedback: Evaluate Your Writing

Many Steps:  Perform the Component Steps for all Components of Your Document

Treat every part of the User Document as if it were a Component.  For example, you will soon work on the User Document’s Overview.  Work on this as if it were a Component, following the steps that I described above.

Listen:  DoAllComponents.mp3

Do It: Put the Components Together: High Level Topics Overviews

Your Components fit into your User Document Outline, which is the structure of the User Document.  A Component may be a topic in the User Document Outline or a collection of topics in the User Document Outline.  Since your User Document Outline has structure, there will be higher-level topics and subordinate or lower-level topics. 

In this Step you will write the Overviews for the higher-level topics in your outline that include Components (sub-topics), but that you have not yet written about.  Think of this as being the Overview for a collection of topics or Components.

Listen: HighLevelTopicsOverviews.mp3

Read: Write the Overviews for the Higher Level Topics

 

The first part of your User Document will be an Overview.  You now know what you have written about in your User Document.  It is time to write the Document Overview (especially the third component, Goals and Purposes of the Document) to match what you have written.

This Document Overview consists of four parts, three of which we will work on here:

O     Description of Your Reader;

O     Description of Your Product;

O     The Goals and Purposes of the User Document that you are writing.

Listen: WriteDocOverview.mp3

Read:  Writing the Overview for the User Document

"Read This First" Section

The fourth part of the Document Overview should be at the front of your User Document.

Here you will use the material that you were gathering for the "Read This First" Section of your User Document.

Listen: ReadThisFirstSection.mp3

Read: "Read This First" Section

The "If You Are…Then Read This…" Section

Providing an "If You Are…Then Read This…" section provides a guide to your Readers.  It is an optional section and should be included only if you have time to do so in the documentation project.

Listen: IfYouAreThenRead.mp3

Read: If You Are…Then Read… Section

 

The next several steps involve getting ready to publish your document.  Here we will test and proofread the document.  Of Course we will consider (and make) any changes that our tests and evaluations suggest.  Finally, we will discuss what’s involved in supporting your document.

Work on all sections of the User Document the same way that you did for the Components. Thus you could be writing one section, while another section is getting proofread.  Don’t wait to have the entire document written before sending it all out to the editor or proofReader.  Instead, prepare Components for editing (as described in the next Steps) and send the Components to your editor.

Evaluate and use the feedback from your Components Readers, editor, and Users to improve your writing.

Do It:  Resolve any Remaining Unknowns

The goal of this Step is to remove any of the unknowns (items that you identified by “???” or whatever string of symbols you chose to identify unknowns when you wrote your text) remaining in the document.

You can do this in either of two ways:

1.  The quick method.  Use the search mechanisms your computer operating system provides to find text in your document files.  Search for the “???” (or whatever string of symbols you chose to identify unknowns).  Resolve the unknowns.  Do this by inserting the graphic or link, answering any questions you might have left in the text, or do whatever it takes to get rid of the unknown.

2.  The slower method.  In this method you read the entire document and look for and resolve unknowns that you identified with the “???” or whatever string of symbols you used.  The advantage of this method is that you get another chance to review and revise the document.

No matter how you resolve the unknowns, you must get it done.  You cannot let the document be published with these unknowns remaining.

Do It: Add Appendices to Your Document

When you were generating the topics for your User Document, I mentioned "Additional Information," which probably will go in an Appendix.  I hope that you followed my suggestion about adding items to the Appendices as you generated the topics and as you wrote the material for the topics.  If so, then the Appendices will almost be done.

If not, take the opportunity to go over your writing, and find the information that should be added to the Appendices.  Add that information.

Review and revise your Appendices.  Publish them for the Components Readers' comments as you did for all of the Components of the Course.  Get approval of the Appendices.

If you are including a glossary in your User Document

If you left definitions out of your Glossary (so you would not interrupt the writing on your Components), then add the Glossary definitions now.  Add any other relevant words and definitions to your Glossary.

Publish the Glossary for the Components Readers and for approval.

The best information is useless unless the Reader can find it.  In this Step you will provide the best access to the information in your User Document.

Although an Index is intimately related to Access, you should complete the Index only when the body of your User Document is completed.  This way, you will not affect the page numbering in the index with changes that you might have to make in the body of the document.  We will finish the Index in a later Step.

Listen: DocumentAccess.mp3

Read: Make it Easy for Your User to Find Information in Your Document

Do It:  Assemble the Complete Document from its Components

Most likely you created the document by using more than one word processing file.  I suggested this in the section "Writing Inside the Box."  Now you should combine the separate files into a single document (if that is how you are going to publish your document).

Learn: About indexing with your word processor, or whatever software you will be using for generating an index.

Do It:  Format the Pages so they Match the Publication Medium

In this step, you should ensure that when the document is published, the page numbers match the medium in which the document is published.

For example, if the document is to be printed, print out a portion of the document.  Make sure that the page number that the word processor software "sees" is the same as the pages.

If You Are Publishing your Document as an AcrobatÔ .pdf

Even more important, if you are going to publish the document electronically (such as in Adobe Acrobat -- pdf -- format) you must manipulate the page "printing" parameters so that the page numbers that your document shows are the same as shown by the Acrobat Reader.  It's really a bother to look in a (dumb) table of contents of a pdf document to find something is on page 27, and when you tell the Acrobat Reader to jump to page 27 you wind up on the document's page 35.  Make sure the page numbers agree!

This can be a simple as making sure that the printer you choose for your word processor to "print" the document (which will really be an Acrobat .pdf document) is the printer that came with your Adobe package (Distiller, Adobe PDF or whatever).  I promised not to talk about specific software, so I have to leave it between you and the software that you will use to create the final form of the documentation to get things working.

Check that when you view your document in the electronic viewer (Acrobat or whatever) the page numbers on the pages agree with those in the Table of Contents, and (most importantly) on the page numbers that the electronic viewer (for example, Acrobat) displays.  If they do not match, correct things so they do.

If you used your outliner in your word processor, then it will have assigned headings to the main structure of your document.  Now (perhaps this is only true for the Microsoft Word with the Adobe Acrobat macro installed in it) if you use the Acrobat macro, then pdf creation software will automatically generate bookmarks (what Adobe should call a Table of Contents). 

Reminder: If the document is meant to be read electronically, then make sure that you do NOT use multi-column text.  You will force your Reader to scroll up and down the pages.  That's not nice.

Do It: Index Your Document

In this step, you will not only mark the text for your document's index, but you will also review and revise your writing an additional time. 

Every time you have the opportunity to re-read parts of your document, take that as an opportunity to polish it some more.  Danger! We are never working toward the perfect document; we only want progress, not perfection.  Perfect documents rarely get finished.

Listen: IndexDocument.mp3

Read: Indexing Your Document

Do It: Final Document Testing

You have written all of the Components of the User Document.  As part of that process, you tested each Component to see if it guided the User in the tasks that they need to perform.  The Components are essentially completed and tested.

The final document testing involves testing the User Document’s access mechanisms to enable your Reader to find the Component that they need to answer their questions.  These access methods include:

O     Table of Contents

O     Index

O     Search

Essentially here you will use your list of basic and advanced things that your Reader might want to or need to do with your document.

Using that list, use the three access methods (Table of Contents, Index, and Searches – using aliases that your Reader might employ) to see if the access methods bring the Reader to the relevant component of the document.  (The relevant component of the document is the place in your User Document that answers the question your Reader might have.)

If you find that the access methods fall short of the hypothetical User’s needs, then improve them by

O     Improve the titles or add titles to the Table of Contents

O     Adding items to the index
Or removing items that lead the Reader on false paths

O     Improving the search by adding more synonyms to your Components pages so that the words that your Reader might use will be found by the search.

Look over the User Document from your User’s point of view.  Does it meet their needs in using your Product? Does it have all the information that the User needs?  Is that information easy to find?  Review and revise the Document one more time.

Investigate the following:

O     Are all the User Interfaces and their messages described in the User Document?
User Interfaces are all the screens, lights, beeps, buttons, controls, knobs, covers, etc by which your User interacts with the product.

O     Does the User Document match the product?

Make corrections as necessary.

Do It: Pre-Publication Review

There are three components to this Final (Pre-Publication) Review:

1.  Compare the User Document with the Product.  Ensure that the User Document matches the product.  Contact the development team to determine what parts of the Product might have changed since the related Component of the User Document was written.  Make any changes to get the Product and User Document in synchronization.

2.  Make sure you have all the necessary Legal Information in the User Document.

3.  Submit the entire document to an Editor. This is an optional step.  If you feel that the document is acceptable, then you can bypass this step because: 

O     You did have each Component of the Document edited. 

O     Earlier in this Course I suggested that having multiple writers is no problem.  Users read the parts of a User Document separately (they do not compare the writing in one piece of the Document with the writing in other pieces).  Thus a unified writing style is a low-priority luxury.

 

4.  Get the Document Proofread.  A proofReader can check for typographical errors, misspellings, or layout errors. Here is a Wikipedia description of Proofreading.  

Fix all errors and take a final quick look at the User Document.  Fix any problems you find.

My Acme battery-operated hair clipper comes with "instructions" that do not tell the Reader how to use the product, but rather is a list of irrelevant warnings.  They are irrelevant because they were written for Acme's AC power line operated products.  Electrocution is unlikely from a 1.5 Volt battery.
Even this one page sheet should have been proofread.  The "instructions" included this line:
"… keep air away from air vent."
Proofreading would have changed this to:  "… keep hair away from air vent."

You should re-publish (internally, for your Components Readers) any parts of the User Document that may have changed.  Ask for comments, but say that at this late date in the User Document production changes are not guaranteed (unless critical) to be implemented.

You must do a Pre-publication review of the User Document.  The User Document for my MP3 player was published with this text (exact copy):
During the playback of a recorded file, if one press the Select Button long, The player will display the confirmation message of deleting the file or not.
Most of the MP3 Player User Document is OK…this bit of text missed the Pre-publication review. 

Review your entire User Document before it gets published.

Do It: Publish the Document 

Produce the final form of the document, or pass it on to whoever will do the final publication.

 This may be any combination of printed and electronic components.  Electronic components might be web pages, a manual in electronic format (PDF, HTML),  Help files, or whatever.  In any case, this should have been specified at the beginning of the project, when we worked on the Document Specifications.

Review the User Document in its final published form.  Make sure:

O     The document accurately reflects the product

O     The document has all of the pieces it should have (some may have gotten lost when published)

O     The navigation of the document works.  Make sure references or links to information in the document are accurate.

O     All legal (including copyright, trademarks, cautions, warnings and warranties) information is placed appropriately in the document.

 

I also recommend that you publish the User Document on the Internet website where you support the product.  Users often lose or discard documentation.  Publishing the User Document on the Internet benefits people who purchase your product second hand. 

 

Do It:  Support the Document

You should support your User Document and product on the Internet.  If you are publishing the document in electronic form, then a downloadable copy on the website is the minimum support.  Make changes as necessary to the document to keep it current with what you learn about the product.

Add new documents to the website as you create new versions of the product. 

Keep the old documentation.  I believe that it is smart for a company to make the documentation easily available to the original owner and any subsequent owners of the product.  Good User Documentation makes Users effective with your product.  Effective Users are good salespeople for your product. 

Listen: SupportDocument.mp3

Read: Support Your Document

 

Did This Course Cover Everything You Need?

I hope so.   But if you have any questions, remember that you have a year of free e-mail support about topics covered by the Course.  My e-mail address is on the Course Support Page.

Your Next Steps

·         Be creative with your User Documentation.  But be creative in ways that help your documentation meet its goal: to help the User to be effective and comfortable with your product.  Don’t get fancy just for the sake of being fancy.

·         Explore new ways to provide support for your Users. 

·         In any case, remember that you and your organization are responsible for what you write.  Consider applying the topics in this Course, but always weigh them against your corporate and industry standards and safety. 

Read: Enhancing Existing Documents

Read: Creating Quick and Dirty User Documentation

 

Read: Reference and Topic Details

Read: Speaking, Revising and Clarity of Writing

Read: Troubleshooting and Technical Support

Read: Use Cases & User Stories

Read: The Future of User Support

Read: How To Explain Things to People

Automobile Cruise Control

This is a relatively complex example, as it deals with a feature that works in modes.  A Cruise Control can be off, on, or on and active (when it is controlling the automobile’s speed).

This reading presents a first draft and listing of items to be included in a User Document about the Automobile Cruise Control.

Read:  A Complex Example: Automobile Cruise Control.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


Resources for Writing Great User Documents:  http://www.greatuserdocs.com

 

(c) 2006 Igetitnow! Training, Inc.