The Most Basic and Indispensable Parts of a User Manual

How do you explain the most important parts of a technical document, say a “User Manual,” to a complete beginner?

I actually had that challenge when a student who has registered to one of my online courses admitted that he did not know where to quite begin writing his manual and what to include in it.

One of the things he did, for example, was to list all the GUI components that he saw on a screen of the application he was trying to document. I had to explain gently that a list did not exactly add up to a user manual.

That got me thinking about the sine qua non conditions or elements that make up a technical document.

For starters, a user guide must of course have a title and at least a single sentence describing its purpose and audience.

Then should come a set of procedural instructions. The instructions should tell the user exactly how to accomplish something by following logical and sequential steps.

If it’s a single-step instruction, it should start with a bullet. If it’s a set of multiple-steps, then each step should start off with a number. They should be presented as a numbered list. That’s as basic as it gets.

But how should each procedure go?

For one thing, it should start with a command expressed via an action verb like “Click”, “Open”, “Go to”, “Select” (my favorite), etc.

GUI components sometimes determine the action verb you should use. For example, if you’re dealing with a check-box, there are only two verbs you need to use: “Select” and “Clear”. Period.

One other component (even though it’s not indispensable) is a screen shot, photo or an image (a “figure” in tech writing parlance) that would help the user understand, follow, and implement the procedural instruction better. One of course should never use any images in a technical document for decoration or aesthetic purposes.

Another traditional component is the heading that precedes the procedural step. This heading is usually in the form of an incomplete “stem sentence” like “To do XYZ:”, followed by the procedural step(s).

All user manuals are basically a combination of these basic units in different numbers and complexity, plus other optional components like tables, sidebars, index, TOC, etc.