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.
Download the full Course (free, no-strings-attached) here.
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.
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).
the printed page over to get a feel for how the Course will progress.
what it says to do in each section of the Course:
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.
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.
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,
It is noble to help others to get their good works done. Barry Millman
What Users want from good User Documentation:
O How to use the Product
O How to fix things that go wrong
How to be protected:
O To learn about the product
Read: About User Documentation
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.
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.
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!
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.
Here are the assumptions that I am making about you.
These are the skills, attitude, knowledge and experience (completed items) 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 (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
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.
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.
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.
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.
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…
Use your actual documentation project as your case study. This Course will guide you through to the successful creation of an effective User Document.
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
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.
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.
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
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
Four Dimensions of your Reader/User
Goals and Mechanics of the User Document Itself
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.
This Reading describes the generic layout of your User Document, that you will produce in this Course.
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.
Read: About Overviews
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)
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
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.
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.
Read: Get Legal Information
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
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.
This information will help you feel better about the writing process.
Your tools include the people you work with, as well as your "word processor" and its capabilities.
Read: Your Writing Tools
Read: Writing Notation
Read: New Technologies In Content Management
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
Using the Product
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.
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 "
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:
Must Do in order to get the product to work.
Wants (or Needs) to Do with the Product.
Cannot Do with the Product.
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
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
Move the Product
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.)
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.
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.)
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:
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.
Save it in your word processor’s native format.
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
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.
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
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
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.
The second are Appendices to the document.
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.
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 Technical Information about the Product
O Where to Get More Information (including a Bibliography, product Web site)
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.
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.
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
Make a reference to the file name of that Component's
word processing file in the appropriate place in the User Document Outline.
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.
This deals with unpacking, setup, installation, and related topics.
Read: Preparing to Use The Product Section
This deals with the variety of ways to start up and how to safely shut down the product.
Read: Starting and Shutting Down the Product
Here we create the part of the User Document outline that deals with the actual usage of the product.
Read: Generating the Topics for the “Using the Product” Sections of Your Document
Read: Care, Maintenance, Storage and Disposal
Read: If You Are Having Trouble Generating the Topics
Read: Fitting Important Topics That Might Not Fit
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
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
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.
Publish the overall High-Level User Document Outline
for your Components Readers. We
discussed this in Internal Document Publication.
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 …
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.
Here's what we've done so far:
You created a list of attributes (SAKE) of your
You have a list of the tasks that your Reader does
with your product.
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:
For Wordwhacker's formatting section we might have:
Undo and Other Tips
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.
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.
Read: Selecting a Component
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
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.
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
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.
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.
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
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.
Read: Component Information Access
Here you will test the Component on yourself.
Read: Test the Component
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.
Read: Let Your Components Readers Review the Component
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.
Read: Test The Component on Others: General Guidelines
Read: Prepare the Material for the ProofReader/Editor
Read: Send the Component to the ProofReader/Editor
You should be working on another Component while your editor is working on your material.
Read: Repair the Component Based on the ProofReader/Editor’s Work
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
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!
Here you can learn to improve your writing from the Iterative, Interactive Process we are using to create the User 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.
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.
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.
Read: Writing the Overview for the User Document
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.
Read: "Read This First" 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.
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.
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.
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 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.
Read: Make it Easy for Your User to Find Information in Your Document
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.
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.
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.
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.
Read: Indexing Your Document
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
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
Adding items to the index
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:
Are all the User Interfaces and their messages described
in the User Document?
O Does the User Document match the product?
Make corrections as necessary.
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.
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):
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.
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.
Read: Support Your Document
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.
· 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
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.
(c) 2006 Igetitnow! Training, Inc.