Two Different Types of Software User Manuals in Technical Writing

© Ugur Akinci
In technical writing, there are two different but related types of software user manuals and I call them “Button Guides” and “Procedural Tutorials”.
A FUNCTION or GUI INTERFACE MANUAL explains what each “button”, or the graphic user interface (GUI) element that one sees on a screen, is all about and how does it behave when one clicks on or interacts with it.
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 beginning technical writers can click their way around the GUI and write down their observations. The result is a basic inventory of screen element behaviors.
(Public domain screenshot courtesy of Wikipedia Commons)
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 performance goals of the audience, and the outputs that the software delivers to meet those performance expectations.
It requires an understanding of how the audience (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 audience is trying to accomplish with the product and thus what the software is supposed to accomplish, then he or 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. Without such procedural tutorials, a “button guide” alone is not enough to alleviate customer frustration.
Why frustration? Let’s explain it with an example…
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 perform (in what sequence and combination you need to use all those buttons and controls) 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 manuals since they are complementary and equally necessary.