Writing User Manuals from the Middle Out

You need to write the user guide for a complex product. There must be a dozens of functions and hundreds of tasks that can be performed with the product. Where do you begin? How to start writing? Conventional wisdom says: start at the beginning with an introduction to the product, and work your way through each function or task in the order the customer will use them. Don't! Here's a tip I learned the hard way after my ninth or tenth year tech writing: start in the middle, and work your way outward.

This article presents a method of writing user documentation that you may find easier and more effective than starting at "Chapter 1:"

1. Start by writing procedures for each task or menu option. This is the "middle" of the document, and results in a collection of subsections.

2. Then, add material just before and after each procedure. This is working "from the middle out." The result is a collection of sections.

3. Organize the sections into chapters, and add more material to the beginning and end of each chapter.

4. Finally, organize the chapters into a manual.

I have found that this method of writing user manuals from the middle out saves time, and yields more accurate and useable documentation.

Why Not Start at the Beginning?

When you begin your manual with an introduction to the product, you also begin your research with an introduction to the product. Typically, you ask the Marketing or Sales department to describe how the product will help the user: "What will users do with it?" You ask Development or Engineering to describe the product's structure: "What is it?" You experiment with the product long enough to determine how it's used: "How does the user use it?" Then, you write your introduction. Which will probably contain inaccuracies and be less useful than it could be, for three reasons:

First, you are attempting to describe the purpose of the product ("What will users do with it?") before you have completely experienced using the product. By asking others what the product does, you are only discovering what they believe the product should do. You must first use almost every function of the product to determine what it really does. Remember, the manual is for users and should be written from a user's point of view. You can better convey the purpose and advantages of a product to a user when you have completely experienced the product from the user's point of view. This is why, in the middle-out method, you write the introduction last.

Second, you are describing the structure of the product ("What is it?") before you have experienced how the pieces of the product work together. Describing what the modules of a software application are is not nearly as useful to the user as describing what those modules do, and how they work together. You can best determine what they do and how they work together by experience.

Third, you usually develop the outline for your manual at this stage. Remember that the outline will determine the order in which you present the product's functions and tasks. And, you have not yet performed all of the product's functions and tasks. After you have experienced a complete cycle of using the product, you will be qualified to determine the order in which to present the procedures for using the product. At this point, determining the order for these procedures is guesswork.

In sum, when you begin writing a manual at Chapter 1, the manual becomes a diary of your learning curve. The first sectioins tend to be either ambiguous or self-obvious. They become ambiguous when you are conscientious enough to attempt to state something meaningful about the product, when have yet to gain real experience with the product. They become self-obvious when you attempt to state only those facts of which you are sure. Because you have little more experience than the reader, those facts will tend to be self-obvious. Starting in the middle and working outward avoids these problems.

How to Do It

To create user documentation from the inside out, follow the suggested steps below.

Write the Sections

Following the steps below will result in a collection of sections. Later, you will organize these sections into chapters, and then a manual.

1. Write the directions for each task or function.

Let's assume one of the tasks the user performs with the product is, "Create a new record." Write directions for this task. Don't worry about:

• The purpose of the task (Why create a new record).

• Where it fits into the big picture (When to create a new record).

• What the user must do or know before performing the task (Prerequisites for creating a new record).

The only thing you are writing is how to perform the task at hand.

Repeat this for each task or function the user can perform with the product. When you finish, you will have a collection of directions for performing all possible tasks or functions with the product. Label this paragraph "Directions."

2. Add prerequsites in front of each task.

Add a paragraph of prerequisites in front of each task. In our example, the prerequisite might be that the product must be in a particular mode before creating a new record. This paragraph should tell the user only and exactly what conditions must exist before the procedure can be carried out. Label this paragraph "Prerequisites."

3. Add results after each task.

A results paragraph states what the user should see to confirm that the task was successful. It also states what has changed as a result of the task. Label this paragraph "Results."

4. Add background knowledge before the prerequisites.

Examine each task and determine exactly what the user must know to successfully perform that task. Put exactly and only the background knowledge the user must know for a task immediately before the prerequisites for that task.

If several tasks require the same background knowledge, you should probably organize them into a chapter or section and place the background knowledge only once at the beginning of that chapter or section.

5. Add next steps after the results.

State what user must, should, or can do next.

After following the five steps above, you have a collection of procedures. Each procedure comprises a section, consisting of:

• Background information

• Prerequisites

• Directions

• Results

• Next steps

Organize the Sections into Chapters

Only now that you have performed every task possible with the product, and determined the prerequisites and results of each task, can you see how they fit together into the overall process of using the product. Now you are ready to determine the proper sequence for performing the tasks, the purpose of each task.

Organize the sections (procedures) into logical groups. You may organize the procedures in the order in which the user is most likely to perform them. Or, you may group procedures with similar functions together. Whatever scheme you choose, each group of sections becomes a chapter.

Now examine the procedures in each chapter and ask, is there any information that the user must know to perform these procedures? At the beginning of each chapter, add exactly and only the information the user must know to perform the procedures in that chapter. Label this section "Introduction."

Determine the Purpose of Each Procedure

Good user documentation doesn't tell the user only how to perform a procedure. It also tells the user when. Now that you have experienced and organized all of the tasks for the product, you are qualified to determine when it is appropriate to perform each procedure. A "When this... Do this..." table is one effective way of presenting this information. You can place this "When..." information in:

The introduction to the manual. You would probably include "When..." information for all of the procedures here. This is usually the easiest place for the user to find the information.

The introduction to each chapter. You would probably include "When..." information for only the procedures in the chapter here.

Each section. You would probably include "When..." information for only the procedure in the section here. This is usually the most difficult place for the user to find the information.

Finally: Write Chapter 1

Now, look at the whole manual. Is there any background info that a user must know before using any of the procedures in the whole manual? Write it down. Call it "Chapter 1: Introduction."

Assemble the chapters, generate a table of contents, and you've got yourself a manual!

Balancing Act: Keeping Your Screen Movies Small and Beautiful

Screen recordings are a valuable tool for enhancing training, tutorials, manuals and websites. Companies use this technique to produce streaming and downloadable content. The recording tools are readily available and affordable.

In this article, we explore some techniques, tips and tricks for recording sound, mouse movement and happenings from your screen to an AVI file.

File Size vs. Movie Quality

One key to successful screen movies is keeping the files small. Larger files mean longer processing times for you and longer download times for your users. Especially large screen movies may not play at all for some users with outmoded PCs. Also, large files do not stream well over the Internet.

Unfortunately, larger files result in better quality movies. More colors, smoother action, and higher quality sound are all benefits of larger file sizes. Therefore, your most important - and most difficult -- decisions will balance file size against quality. This article presents technique for keeping file sizes small while retaining the quality you need in your screen movies.

Tip 1: Select Your Color Settings

Before you record a screen movie, you need to configure your display for color depth. We recommend setting your color depth to 256 colors, or 8 bits. In Windows, you do this by selecting Start | Settings | Control Panel and then double-clicking the Display icon.

Today, many computers work in True Color. True Color uses 24 or 32 bits per pixel, and can render millions of colors. Let's assume you're capturing an area that is 320 by 240 pixels. That's 76,800 pixels for every complete frame captured. How much storage space would each complete frame in this movie occupy?

Bit Depth	Colors	Storage Space per Complete Frame (320 by 240 pixels)
8	256	76,800 Bytes (76.8kB)
16	64K	153,600 Bytes (153.6kB)
24	16.7 million	230,400 Bytes (230.4kB)

As you can see from the table above, each frame in True color mode contains a lot of information to capture from the screen memory. This information must then be compressed and written to the AVI file. That process requires a lot of time, processor power, and disk space.

In many cases, the programs that you capture will look as good in 8 bit color mode as in True Color. The capture programs optimize the color map to make the best use of them, so you do not lose much quality unless your subject demands higher color depth. In 8-bit color mode the amount of information to capture and compress is a fraction of that in the other modes. These pictures compress the fastest, and produce the smallest AVI files.

If you must record in higher than 256 color mode, consider using 16 bits, and use Intel Indeo codec, configured to the "Quick Compress" option. If you don't have Indeo installed on your machine, you can download it for free from Intel's web site, http://developer.intel.com/ial/indeo/. On HyperCam, for example, this will compress about 10-20% faster than with the default codec of MS Video 1.

A final word of advice on setting colors: You may be tempted to record in True Color and then convert the file to 8 bit color depth. There are two reasons to avoid this. First, the software you are recording will probably do a better job of picking which 256 colors it displays best in, than the screen recording software. So, set your display to 256 colors and let the application you are recording pick its palette. Second, saving and processing a file in True Color takes more time than in 256-color mode. This extra time is wasted if you're just going to convert to 256 colors.

Tip 2: Select a Frame Rate. How Low Can You Go?

The frame rate is the number of frames per second that you record and play back. Television uses about 30 frames per second, and movies about 60 frames per second. This results in very smooth action. However, frame rates this high create very large computer files.

The frame rate needed for smooth motion depends on how fast objects move across the screen, and on the size of the objects. Small, fast moving objects tend to blink as they move. This occurs when the image of a moving object is present in one frame, but not in the next. For example, a cursor moving quickly across the screen will tend to blink. If your screen movie must include such objects, you'll need a high frame rate: 15 to 60 frames per second. If you keep the action on the screen slow, you can obtain good results with a frame rate as low as 2 to 5 frames per second.

Use these recommendations as a guideline, and experiment with a few settings to see how low you can go with the frame rate. The only way to determine how low you can go while maintaining quality is to record and play back a few samples.

HyperCam, like most screen recording software, enables you to select the frame rate for your recording.

Tip 3: Set Key Frames

Your screen capture software does not store information for every single pixel in a frame. Instead, it stores the information for which pixels have changed since the previous frame. For example, assume two frames are identical except that the cursor has changed position. The capture software will store information for only the pixels that have changed because of the cursor's movement. The majority of the screen stayed the same from the first frame to the second. Therefore, there is no need to repeat this information in the second frame. This storage method saves a lot of disk space and results in faster playback.

However, the longer a movie plays, the greater the errors introduced by this storage method. To correct any errors, your recording software inserts key frames. A key frame is a completely recorded frame, with all of its information intact. Then, beginning with the key frame, the software once again records only the changes from frame to frame. When it hits another key frame, it records the entire frame, begins recording only the changes... and so on, again and again.

Because key frames take more storage space than normal frames, the more key frames in your screen movie the larger the file. In our example of recording a 320 by 240 movie at 256 colors, each key frame occupies 76.8kB.

Most programs will automatically choose every tenth frame as a key frame. Most will also enable you to choose how often to insert a key frame.

If your screen movie contains a lot of zooming, panning, and other movement, you'll need more key frames to keep the quality high (every tenth or even fifth frame). If changes from frame to frame are small, you can select fewer key frames and still retain high quality (every fifteenth to thirtieth frame).

As in choosing the frame rate, the only way to determine the minimum number of key frames for the quality you need is to take a few test recordings.

Tip 4: Select the Recording Region

Some screen recording software enables you to select a specific region or Window to record. You can usually select the recording region in three ways:

• Select an area of you display by dragging a selection rectangle. Everything inside the rectangle will be recorded.
• Select a specific window.
• Specify the X and Y coordinates of the recording area on your display.

The smaller the recording area, the smaller your file size.

The best method for determining the minimum size recording area is practice. Run through the sequence you need to record several times, and determine the minimum size window that the sequence requires.

Also, instead of choosing to record the entire window in which the program is running, consider selecting only the interior of the window. If the window's title bar, scroll bar, and status bar do not add useful information, do not record them.

Some programs enable you to move the recording area around the screen, so that you can pan from one area to another. The resulting movie is like watching a large screen through a small, moving window. This is a powerful technique for showing large areas with a small movie. However, it can be disorienting. Keep the action slow and use narration to clearly explain when and where you are panning.

Tip 5: Select the Right Audio Settings

Most of the space your screen movie occupies is comprised of video information. That is why we have focused on techniques for minimizing the size of the video information while still retaining quality. However, selecting the right audio settings can also minimize file size.

First, determine if your screen movie software enables you to select mono or stereo sound. Unless you have a compelling reason to record in stereo, select mono.

Second, select the proper number of bits rate for the quality of sound you want. Most software enables you to choose between 8 bit and 16 bit samples. Think of a sample as a pixel of sound. The more bits you use to store a screen pixel, the greater the number of colors that pixel can take. The more bits you use to store a sound sample, the greater the frequency response of the sample captured. Try your audio setting at 16 bits per sample, before going down to 8 bits. The difference in sound quality between 8 and 16 bits is usually very noticeable, so this is a good place to spend some file size.

Third, select the sampling rate. The sampling rate is how many times per second the capture software will record sound. For example, a sampling rate of 8000 means that the software is capturing 8000 slices of sound every second. For most screen movies with voice narration, a sampling rate of 11025 gives good quality with minimum file size. This combination of bits per sample and sampling rate is approximately equal in quality to an FM radio.

Screen recordings can be valuable tools for demos, tutorials, training videos and various technical applications. The latest commercial and open source tools provide this capability in easy-to-use and affordable packages - take advantage of this great technology!

Course Evaluations that Matter

Do your course evaluations matter? Do they measure what's really important to your company and your students?

The training courses that you develop and deliver should advance your company's business objectives. This sounds like common sense. Now think back to the training classes that you have attended. After each class, you were probably asked to fill out a course evaluation. How many of those evaluations measured how well the course met the company's or your business objectives?

Too many course evaluations measure how well the course was written or delivered, and not how well the course supported the company's or student's objectives. For example, you have probably filled out course evaluations with a question similar to this one:

Rate the pace of the course:

• Too Slow

• Just Right

• Too Fast

This question helps you determine if the course is good. It does not help you determine if the course met the needs of your company or students. Here is an example of a question that measures how well a course met one of the company's business objectives:
As a result of this class, are you able to spend less time performing the task covered? For example, are you able to spend less time creating a purchase order or travel request, or less time looking for ledgers to view?

• No. It takes me just as long to perform the same tasks as before taking this class.

• Yes. I can perform the tasks covered in class in less time than before.

• This question doesn't apply to me.

One of the biggest challenges in the training profession is measuring return on investment for training. Entire books are devoted to this topic. While a complete treatment is beyond the scope of this article, you can still take steps right now to measure how well your course has met your company's or customer's business objectives.

Interview the course sponsors and/or students, and discover what business objectives they want to fulfill with the course. A business objective is a specific task whose success can be measured.

When you ask course sponsors or participants what they hope to accomplish in a course, their first answer is usually not specific enough. For example, if you are developing a course for a new engine analyzer, they might answer that the course objective is "To be able to use the analyzer." In this case, you would need more specifics. Use the asnalyzer to perform exactly which tests? On what kinds of engines? With what degree of accuracy?

Once you know the objectives being measured, the evaluation questions suggest themselves. When writing the questions, focus on asking the students whether they can now perform the given task better, faster, more accurately, etc. than before.

In addition to surveying the students, you might also consider objectively measuring the students' productivity before and after the class. For example, you might measure how long it takes students to perform a task before and after training, or how well they score on customer satisfaction surveys. These kinds of objective measurements are more difficult than having students fill out post-training evaluations. However, the payoff is a clearer idea of how well your classes support your company's and your students' business objectives.

This article is necessarily brief about how to measure the return on investment for a training course. However, using course evaluation questions that directly address your company's or student's business objectives is a good start. From there, you can move on to more formalized, complex techniques of course evaluation such as those discussed in the books recommended on this site. Your credibility as a trainer, and your company's bottom line, will both profit.