Tip of the month from PRC
 August 1997

Documenting GUI (Graphical User Interface)

Issued 3 August 1997 

We accept Mastercard/Eurocard/Maestro/JBC and Visa!
Tip of the month is edited by Peter Ring, PRC (Peter Ring Consultants, Denmark)
- consultants on how to write user friendly manuals

This month's tip is based on mails to the TECHWR-L from Beth Agnew and Sue Gallagher, added some of my own comments.

Sue Gallagher:

Create an overview section that explains all the menu options and toolbar buttons. This section can be all a power-user needs to get up and running and can serve as a handy reference once the beginner gains experience. Doesn't much matter whether you put this section up front or at the end.

Additionally, use this section to explain all of the implemented user affordances (like drag and drop, double clicking, and accelerator keys). Once you've told the user these affordances have been implemented in the program, forget about them. The one thing that will drive both you and your user toward a marked propensity for lip-diddling is an attempt to explain every way there is to accomplish a task in a GUI. Experienced users will find and use them; new users won't want to know about them quite yet.

Make the rest of the book task based. I generally take a consistent approach of: * Defining the task and discussing its repercussions * Enumerating the steps required to accomplish the task

If the field information goes in the context sensitive help, you can leave it out of the paper book.

Beth Agnew:

I prefer task-oriented explanations with enough visuals to help the user relate to the screen, but not so many screen captures that it becomes overwhelming. I believe in giving the users credit for being intelligent enough to *look* at the screen while working with the manual. At some point you may need to have all of the fields identified and thoroughly explained, but that can be done in a section at the back of the book. The important thing is to help the users

  1. find their way around the product so they can explore and learn on their own (and the interface should help them do that), and
  2. figure out how to do the tasks they bought the program to accomplish.
The screen captures should be pictures of things that are tricky to do or to explain. They should eliminate any confusion, and "be worth 1000 words" by showing the user something in one graphic that would take many paragraphs to explain. Use screen captures where most of your users will see the same thing, not where the image might be different depending upon their OS, configuration of equipment, etc.

Be sure to TEST the manual against the product before release, and make sure your graphics are absolutely correct. If there are changes to the interface after you have grabbed your screen, go back and re-capture. I can't emphasize this enough. If the user looks at the screen and sees something different than what's in the manual, that destroys your credibility. If you have to go to press earlier than the testing phase, try to get commitment from the developers that the interface won't change (good luck!). Or, avoid using graphics of elements that might change.

And if you're very VERY lucky, you will be part of the design team so that you can help make the interface more intuitive for users *before* it's coded, and then your manual won't have to be so long. The interface itself should indicate to users what the implications of choices might be, i.e., whether they'll expect to see a dialog box, or whether an operation will initiate.

Peter Ring:

I fully agree with the above ideas, but I would like to add a few more points and general comments.

I have good experiences with the following system:

  1. An explanation on what is this software really doing, and (if relevant) how does it work together with the ambient world. In some cases it is obvious, but in many cases it is obvious to the programmer, only. Simply describe some typical applications. And make sure they are typical!
  2. A "school" chapter, where I take the user by hand through the filling-in of a few simple examples, often the "typical applications" from point 1 above.
  3. If there are a "recommended standard" for filling in the GUI fields, show it. Explain the reasons for the recommendation, so that the user can know when it's reasonable to use or leave the standard.
  4. The complete information about each window, field-by-field with a filled-in typical screenshot example. I agree with Sue, that in case it is explained in a context sensitive help function, it is not necessary to repeat it in the book, but in that case, notify the users about this system, preferably on each page where the info should have been. Also consider to make a better explanation in the book, if the context sensitive help function was written by the programmer!
  5. If relevant: a list of special or professional terms and abbreviations used, with a short explanation.
  6. If I find something which is awquard, I go back to the programmer with a suggestion for how to make it. Most often the programmer will change it if you can make him/her see the advantages, and see that is is not too difficult to change. Here my general progamming experience has often been a big advantage, because I know something about what's possible, what's easy, what's difficult, and what's not possible.

If you disagree with these ideas - or have other relevant points, experiences, or ideas +/-, please e-mail me !

Ideas for new "Tip of the month" subjects are very welcome, too!

Go to last month's tip .
Go to a list of old tips .
Return to the User Friendly Manuals' homepage .