Programmers Gui Shorthand

ProgrammersGuiShorthand is a pattern for showing users how to navigate a GUI. It is one possible solution to the GuiShorthand problem.

The context and forces for this pattern are on the GuiShorthand page.

Possible Solution:

A GuiShorthand just needs to show what happens next. The principles used in this pattern are:

Use arrows to move from one command to the next.
Show all levels of hierarchical commands, including:
1. Whether a command is a menu.
2. Whether a command is on a right-click menu.
3. Choice of tab on tabbed dialogs.
4. Frame names within dialogs.
Indicate where (or what) to enter into text boxes.
Subtly show the user when they move to another screen.

Examples

This example shows a text box as a blank line:

1) Installer must have administrative rights sufficient to install software on PC.

2) Log in to the PC. User name: ____________ Password: ____________ Domain: OUR_DOM OK

3) Insert the "AutoCAD 2002 Etc." CD.

4) Launch Windows Explorer. For example: Start -> Programs -> Windows Explorer

5) Install AutoCAD. (CD Drive):\Autocad Map 5\setup.exe If errors occur during "Internet Explorer 5.5 Setup" or "Windows NetMeeting 3.01", press "OK" to continue. You know AutoCAD is loaded when you can see the "Autodesk Map 5" icon on the desktop.

(AutoCAD puts the icon in the "All Users" desktop.)

This example uses an arrow notation:

 Uninstall Instructions
 If you need to uninstall AutoCAD:

 1)  Uninstaller must have administrative rights sufficient to install software on PC.

 2)  Log in to the PC.

 3)  If needed, uninstall old software.
     Express Tools  can only be uninstalled while AutoCAD
     (or another program, such as AutoDesk Map 5, that includes AutoCAD)
     is still installed.
     Start -> Settings -> Control Panel  -> Add/Remove Programs  -> Install/Uninstall ->
              AutoCAD 2000 Express Tools -> Add/Remove -> Yes                    -> OK
              Autodesk Map 5             -> Add/Remove -> Remove -> Next -> Next -> Finish -> No
              Land Object Enabler 3.0 -> Add/Remove -> Remove All     -> Next -> Finish
              Arch. Object Enabler 3.0   -> Add/Remove -> Remove All     -> Next -> Finish
              OK
     Close the Control Panel.

Some possible rules:

Show every level of each hierarchy of commands. That way the user only needs to look in one place to find the next command. The description of the next command can be brief because the user is already looking near it.

When selecting a menu item, the first command is to look among the menus. For example, to create a new blank web page in Netscape 3.0 Gold:

  menus -> File -> New Document -> Blank

When selecting an item in a tabbed dialog box, the choice of tab is a command. (Even if it is the default tab, it should be explicitly stated.) Also, each level of nested frames is a command. For example, to use the right-click menu to set the font in Microsoft Word 97:

  (move mouse over document text) -> right click -> Font... -> 
      Font -> Font -> (choose a font) -> OK

Some subtleties that most users won't consciously notice:

Subtly show the user when they move to another screen.
1. Many GUIs use three dots (...) at the end of commands that launch another screen. You can include the three dots in the command name.
2. This convention puts the commands on the new screen on a new line. (Of course, if you run out of space on a line, you should also use a new line.)
Use indenting to show the relative "depth" of the commands.

Resulting Context:

One nice feature of this notation is that it does not need bold characters, italic characters, or other specially formatted characters.
This notation does not explain the mechanics of clicking on buttons, filling in dialog boxes, et cetera. Some users need extra training in these mechanics of using the GUI. This problem can be partially addressed by adding more detail to the first few samples of GuiShorthand in a section. (See variations, below.)
This notation enables LineByLineReview of documentation, because:
1. It is brief enough to document a large project without people's eyes glazing over.
2. It is complete enough that the LineByLineReview's "More extreme version" of quality assurance is practical.
3. It is simple enough for a wide range of users to understand it.

Known Uses:

The two long examples above are taken from manual install scripts at a power company. The users of these scripts are system administrators who are familiar with installing and uninstalling software, but not necessarily familiar with what options are needed to install and uninstall this particular software.
The documentation for NovaPlot used this pattern to give step-by-step instructions for using the software. The varied users of this documentation are described in the LineByLineReview pattern.
The former Cytex.com internet hosting company used this pattern to document Windows and Linux system setup instructions.

Related Pattern:

LineByLineReview of documentation.

Variations:

The NovaPlot documentation often mentions the mechanics of using the GUI. The extra detail appears where requested by the users. The first sample of GUI shorthand in a section usually has more detail. For example, this example given above:

  menus -> File -> New Document -> Blank

might become:

  From the "File" menu -> select "New Document" -> "Blank".
  Or type Alt F N B.

Because this is awkward, NovaPlot has only two layers of menus, not the three layers of menus in Netscape.

Another possible format is given in the SanguineGuiShorthand.

Discussion

Some users will reject this because it does not contain enough information for them to know what to do. In order to fix this, some sort of commenting notation will have to be added.

[RefactorMe: If you think this is the best solution among ProgrammersGuiShorthand, AsciiArtGuiShorthand, and SanguineGuiShorthand, you may want to reincorporate this page into the GuiShorthand page.]

CategoryDocumentation, CategoryPattern, DocumentationPatterns