Documenting GUI Tasks
Problems
with the "Structure-Oriented" Approach
By
Susan Self
Engineers who have become technical writers—or writers experienced mainly in documenting hardware or command line interfaces—may not know how to proceed when faced with documenting software with a graphical user interface (GUI). Their instinct is to produce parts lists or command descriptions. They proceed to dissect every menu in every window and describe the function of every command in neat little tables. This is the "structure-oriented" approach.
The weakness of this approach is that it puts a tremendous burden on the software user to figure out which command or set of commands should be used to perform a desired task. A user typically has a task in mind and turns to the documentation to scan a list of tasks to find the one that matches the pattern in mind. With "structure-oriented" documentation, the user has to scan through many tables of commands—tables organized not by topic, but sequentially according to their occurrence in a menu or interface. Finding an appropriate command for a task this way is tedious, time consuming, and difficult. The experience is equivalent to going to a restaurant and being served all the ingredients of a meal, then having to assemble them and cook the meal oneself.
The structure-oriented approach becomes even more problematic for users when the software application is very large and configurable and entails many smaller tasks to achieve the larger goals of using the tool. In my career, I have twice inherited structure-oriented documents for complex software applications. One tool was for building GUIs, and the other was for planning and simulating cellular networks. In both cases, the product managers were complaining that customers found it hard to figure out how to use the tool. My job was to convert these documents into task-oriented descriptions of the tools and to help users find their way through a sequence of tasks to achieve their goals.
The Task-Oriented Approach
Define GUI tasks. How do you define GUI tasks? I start with the commands in the menus and generate task titles that begin with gerunds. For example, for the Load Configuration command in a File menu, I make a heading called "Loading a Configuration." Then I make higher-level headings under which I group lower-level tasks that are related. For example, for a Problem List Viewer, I have the heading "Managing Window Configurations," under which I have the task sections "Loading a Configuration," "Saving a Configuration," "Saving a Configuration under a New Name," and "Deleting a Configuration." These groupings are rather obvious.
Sometimes I need to play with a tool for a while to understand the function of a command and the tasks in which it is used so I can find an appropriate group for it.
Organize groups of tasks. After I have grouped all the tasks, I organize the groupings into the approximate sequence in which the user will perform the tasks. For example, an introductory section might describe starting and closing down the application and basic configuration tasks to make it fully usable. Often several sets of basic tasks must follow in sequence to complete a goal, so I put these together in a large chunk. In other chunks, I group the less essential or optional tasks, such as customizing the tool display or using special features.
Create the procedures. I find that it is easy to map structure-oriented command descriptions into tasks and then shift around the existing blocks of text into the new organization of the document. After that, I massage the old text and start creating the procedures for the GUI tasks by experimenting with the interface myself. If I'm lucky, I may have a functional specification to help me figure out the commands. A procedure typically has a numbered list of steps with screen shots of the interface being used to make the steps easy to follow. It helps to create a typical example for a feature and show sequential screenshots of what happens with that example.
Create other helpful features. When many tasks involve the same large window, it is useful to introduce the window and its parts at the beginning of the higher-level section that groups the tasks.
Sometimes concepts should be defined before introducing tasks based on those concepts. For example, before using the configuration commands in a configuration manager, the user needs to understand the difference between a "planned configuration" and an "active configuration."
For goals requiring many tasks, it is helpful to create roadmaps, flowcharts, or tutorials to guide the user through the series of tasks or iterations of tasks. The user needs the big picture as well as the detailed steps so as not to get lost.
A good index is another useful aid, enabling the user to identify tasks by topics and to go to them directly rather than through higher-level headings. I sometimes also index every window and command with a pointer to the page where the window or command is used in a procedure. I've found that it is safer to present commands in procedures than in simple command descriptions because in the procedures I spell out the preconditions and warnings related to using the command. This way the user is less apt to perform a destructive action unwittingly in the process of guessing and experimenting.
Finally, when documenting GUI tasks, we technical writers should let sympathy for the user guide us in making the software seem easy to use. Like good hosts, we should try to anticipate every need of the user and provide for it gracefully at the appropriate time and place. When we are successful, the documentation becomes transparent, immediately useful but not calling attention to itself, and the user has a direct and satisfying experience with the software.
