|
How to Create Great User Documentation: A
Hands-On Course 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. Back to the GreatUserDocs Home Page Download the full Course (free, no-strings-attached) here. Using This MaterialYou 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. 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 ResourcesWriting Notation 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.
How to Create Great User Documentation: A Hands-On Course Course Topics and Overview About YOU, the Person Taking this Course You, When You Have Completed This Course. Your Ongoing Course Assignments 1. Read Anything Professionally Written 2a. Read This Specific Piece of User Documentation 1. If You Are Now Writing or Starting to Write a User Document 2. If You Are Not Now Writing a User Document (and don't have one planned) Preparing to Create Your User Document How You Will Write Your User Document The Structure of Your User Document Background Material: Things to Keep in Mind Documentation Project Management Do It: Request “Legal” Information for Your Document What You Should Have Completed or Are Working On Writing The Educational Part of Your Document Generating Your User Document Outline User-Product Life Cycle (U-PLC) High Level User Document Outline Getting & Saving the User Document Outline File Modifying the User Document Outline Filling In the User Document Outline Do It: The "Preparing to Use the Product" Section Do It: Product Startup and Shut Down Do It: Generating the "Using the Product" Topic List Do It: Care, Maintenance, Storage and Disposal of Your Product If You Are Having Trouble Generating Topics Optional Reading: Organizing the Topic Lists Do It: Checking the Topic Lists Do It: Internally Publish and Get Approval for the Outline Writing the Components of Your Document Do It: Choose a Component to write about. Do It: Analyze the Component and Extend Its Outline Do It: Write About the Component Do It: Submit Graphics to the Artist for First Draft Do It: Review and Revise Your Writing Do It: Improve Access to the Component’s Information Do It: Test the Component 1: Preliminary Testing Do It: Publish the Component for your Components Readers Do It: Testing the Component 2: More Formal Testing Do It: Prepare the Component for the Editor Do It: Send the Component to the Editor Do It: Repair it Based on the Editor’s Work...Then back to the Editor Do It: Add Graphics to the Component Publish the (close to Final) Component for Your Components Readers Evaluate/Modify Your Writing Techniques Many Steps: Perform the Component Steps for all Components of Your Document Do It: Put the Components Together: High Level Topics Overviews Writing Your Document's Overview The "If You Are…Then Read This…" Section Do It: Resolve any Remaining Unknowns Do It: Add Appendices to Your Document If you are including a glossary in your User Document Provide Excellent Access to Your Information. Preparing to Publish Your User Document Do It: Assemble the Complete Document from its Components Do It: Format the Pages so they Match the Publication Medium If You Are Publishing your Document as an AcrobatÔ .pdf Did This Course Cover Everything You Need? Appendix A: Improving Existing Documentation. Appendix B: Miscellaneous Topics
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. 3. Do
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. Welcome to the CourseListen: 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 DocumentationWhat 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: O To learn about the product
Read: About User Documentation Goals of Your User DocumentYour 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 CourseLearn 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 CourseListen: 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 CourseListen: 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, NowHere are the assumptions that I am making about you. Read: Where I Assume You Are Now You, When You Have Completed This CourseThese 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. About Me, Your InstructorI am passionate about good communication. My corporate website www.igetitnow.com contains my thoughts on this topic. I believe that “information oversights” (where we leave out information that our audience needs) is a cause of confusion, anger, and expense to our audience and to us. I invite you to look over some of the information in the “Reading Room” at www.igetitnow.com (linked at the left of the page). Read: Some of My Thoughts on User Documentation My resume is at: http://www.igetitnow.com/resbarry.html The Acme CorporationListen: 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 Assignments1. Read Anything Professionally WrittenYou 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. 2. Read User DocumentationWhile 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 DocumentationThe 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.
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 DocumentUse 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 DocumentListen: 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 DoListen: 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 SpecificationsListen: 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 2. The
Product 3. The
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. The Structure of Your User DocumentListen: 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 MindListen: 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 ManagementPlease 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! Do It: Request “Legal” Information for Your DocumentYour 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. Listen: Legal.mp3 Read: Get Legal Information What You Should Have Completed or Are Working OnO 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 ShouldO 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 OverviewThis information will help you feel better about the writing process. Listen: WritingBackground.mp3 Read: Writing: Overview & Background
Your Writing ToolsYour 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 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 OutlineListen: 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 AnalysisEarlier, 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. O
Wants (or Needs) to Do with the Product. O
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 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 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 OutlineYou 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 FileListen: 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: 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.
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.
Modifying the User Document OutlineYou 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! 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 InformationListen: 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.
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 Troubleshooting O
Adjusting Parameters 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.
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. ComponentsLater, 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. 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" SectionThis deals with unpacking, setup, installation, and related topics. Listen: PreparetoUseProduct.mp3 Read: Preparing to Use The Product Section Do It: Product Startup and Shut DownThis 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 ListHere 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 ProductRead: Care, Maintenance, Storage and Disposal If You Are Having Trouble Generating TopicsListen: TroubleGenTopics.mp3 Read: If You Are Having Trouble Generating the Topics Read: Fitting Important Topics That Might Not Fit Optional Reading: Organizing the Topic ListsIf 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 ListsConsider 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 NowAt 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 OutlineO
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 … Writing the Components of Your DocumentListen: 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. ReviewHere's what we've done so far: O
You created a list of attributes (SAKE) of your
Reader. O
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: 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 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 OutlineNow 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 ComponentYou 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 DraftAs 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) |