Inside Macintosh: Apple Guide Complete / Part 1 - Designing Guide Files

Chapter 2 - Authoring Tips and Suggestions

Designing Branches

A panel branch (known here as a branch) is a sequence within another sequence. With branches, you can effectively present choices or context-specific instructions to the user under a single topic with a short direct name. You should always use branches to let the user

• choose one of several help instruction options that are mutually exclusive
• choose one or more help instruction options for information that is parallel or highly related
• automatically receive help instructions about a specific condition that you can verify with context checking
• choose to view help instructions about a specific condition that you cannot verify

When designing your help, reduce the number of topics in the access window, keep topic names short and direct, and provide help that is specific to the user's context. Avoid creating separate topics for tasks that are highly related to the same goal or feature. And don't create a sequence that describes several separate tasks sequentially. If you do, you force the user to navigate through panels to reach panels of interest. If the length and style of your topic name don't conform to the suggested style in this chapter, your sequence might require a branch or you might be describing the branch in the topic name rather than only the topic goal. For more information, see "Designing Topic Areas and Topics" beginning on page 2-37.

You can have Apple Guide display a branch to the user automatically, or you can have the user enter the branch from a button linked to a built-in function or from a decision panel using checkboxes or radio buttons. (For more information on decision panels, see "Designing a Decision Panel" on page 2-58.)

IMPORTANT

The Guide Script commands used to create a branch determine whether the user can return to the original sequence or to the access window. Wherever possible, create a branch from which the user can return to the original sequence. See the chapter "Guide Script Command Reference" for more information.

The rest of this section provides details on creating branches.

Designing Branches for Mutually Exclusive and Related Tasks

A guide file topic can contain instructions that are mutually exclusive (for example, several tasks that accomplish the same goal) or that are highly related to each other (for example, parallel tasks or tasks that occur in the same place). For both kinds of tasks, you should create a branch that the user accesses through a decision panel. Use radio buttons to give the user only one choice among several options and use checkboxes to give the user the choice of one or more options.

The following example calls for radio buttons. The SurfWriter application lets the user enter a word in the dictionary using either menu commands or a script. Rather than presenting a separate topic for each method (for example, "How do I enter a word in the dictionary using menu commands?" and "How do I enter a word in the dictionary using a script?"), the guide file instead uses a topic name that describes the main goal ("How do I enter a word in the dictionary?") and creates a branch for each method. Because both branches accomplish the same goal, the user selects only one of the branches from a decision panel with radio buttons.

This next example calls for checkboxes. Macintosh Guide uses a single topic for the question "How do I change the time and date formats?" because both of these tasks are accomplished in the same place, the Date & Time control panel. The sequence contains a separate branch for each task. Unlike the previous example, these tasks are not mutually exclusive; the user might want to change only the date format, only the time format, or both. Therefore, the user can select one or both branches from a decision panel with checkboxes.

For more information, see "Using Radio Buttons and Checkboxes" on page 2-78.

Designing Branches for a Specific Condition

A guide file topic can include information that specifically applies to a condition of the user's environment or context (for example, information that applies only if particular software is installed on the user's computer).

For this specific information, you can create a branch that the user selects or one that is provided automatically. If you can check the condition programmatically, you should use the <If> and <Else> commands or the <Skip If> command to have Apple Guide automatically show the appropriate branch to the user. Otherwise, you should have the user choose the appropriate branch from a decision panel.

For example, assume that your application provides two methods for checking the spelling of a document: one uses the standard dictionary and special thesaurus, and the other uses only the standard dictionary. Because you can verify whether the user has installed the thesaurus, you can create a branch for each method using the <If> and <Else> commands. In this way, Apple Guide verifies whether the thesaurus is installed and automatically presents the appropriate branch to the user.

In contrast, assume that your guide file contains the sequence "How do I print a document?" Your users need to view only those panels that apply to their particular printer type--in this case, a LaserWriter or ImageWriter. You create a branch for each printer type. And because you cannot use context checking to verify the printer type, you provide a decision panel from which the user can choose the appropriate branch.