How to Write Two Different Types of User Guides

TECHNICAL WRITING | Tech Com Center





© Ugur Akinci

In technical writing, there are two different but related types of software documents and I call them “Interface Manuals” and “Procedural Guides”.

An INTERFACE GUIDE explains what each button, or the graphic user interface (GUI) element that one sees on a screen is and does.

For example, such a button guide would explain that if you click the File menu option, a drop-down list will display other sub-options including Save and Save As, etc.

Such guides explain in a static manner what the response will be when you click on various text links, menu options and command buttons.

These are relatively easier to write since all you need is the software itself. Even a beginning technical writer can click her way around the GUI and write down her observations. The result is a basic inventory of screen element behaviors.

A PROCEDURAL GUIDE, on the other hand, is a much harder document to write because it requires not only a thorough knowledge of “which button does what,” but also an understanding of the basic functionalities, basic outputs that the software delivers.

It requires an understanding of how the clients (end users) actually do use the software and what they expect the software to accomplish.

Once the writer has a clear idea about what the software is supposed to accomplish, then she can identify the procedures that are most important for the user and for the system administrator who is supposed to configure the system.

The writer’s task is to break down those procedures into sequential, mutually exclusive and non-redundant steps so that the user can follow the tutorial easily.

These are the sort of complex documents that novice technical writers find harder to author. But without such procedural tutorials, a “button guide” alone is not enough to alleviate customer frustration.

Why frustration? Imagine you are trying to fly an airplane and the “User Guide” you have identifies and explains what each and every part and button on an airplane does WITHOUT however actually explaining what sequential steps you need to take (in what sequence and combination you need to use all those buttons and controls) in order to fly the airplane. Wouldn’t you be frustrated if you lacked such a procedural tutorial?

An ideal software manual set includes BOTH types of documents since they are complementary and equally necessary.

Have a Great Tip, Photo or Comment About This Topic?

Do you have a great tip or photo about this? Something that you believe we should read or see? Contribute and share it today!