Jeanne's World    Apple Guide Place        Apple Guide FAQs

How do I write a helpful Oops panel?

Apple Guide offers a construct called <make sure> to let you ensure that your instructions will make sense in the user's current context. To use <make sure>, you specify a condition; if that condition isn't met, then Apple Guide presents the user with a special panel, called an Oops panel.

A helpful Oops panel is aimed at assisting the user to correct the problem. This problem may be due to a number of reasons, and your Oops panel should be worded appropriately for each:

• The user may have failed to complete a step - for example, if the user didn't open a dialog box, and your next panel requires that the dialog box be open. Your Oops panel needs to reiterate this step.
• The user may have moved to an incorrect context. One of the most commonly-seen reasons is the user clicking the desktop and switching to the Finder. In this case, your Oops panel needs to tell the user how to get back into the necessary context before proceeding.
• The user's setup may not be ready. For example, a needed control panel may be missing or inactive. Your Oops panel should tell the user how to fix the setup so the task can be done.

No matter what the cause of the problem is, there are some general guidelines that apply to any Oops panel:

• Format the panel so it's obvious that there's a problem.
  
  (Take a look at Apple Guide Complete for another example.)
• Make the Oops panel's wording as neutral as possible; instead of "You did not do the step correctly", use "The dialog box must be open before you can continue." The first wording can intimidate a user who's already uncertain; the second focuses on the needed condition rather than the user's failure.
• If you're correcting a failure to complete a step, don't copy the instructional wording you used on the previous panel; the user may not have understood it. Phrase the step a little differently, giving more help with the details. If the previous panel said "Choose Page Setup from the File menu", a helpful Oops panel might read "The Page Setup dialog must be open before you can continue. Pull down the File menu and choose the Page Setup item."
• Focus on getting back on the track of instruction, rather than on giving the user additional background. The user is normally reading your guide in order to do a specific task, one that may be urgent, and may be impatient with more than the minimum of needed information. When writing a guide, less is usually more.
• Check for setup problems as early in the sequence as possible. If the user will need to install an extension in order to do the task, it's best to say so up front, rather than after several minutes spent doing preliminary steps.

The Auto Open panel is a special type of Oops panel. An Auto Open panel has an attached AppleScript that is executed when the panel opens; the AppleScript automatically performs the necessary action so the user can continue. For example, if you use a <make sure> to check that the user has opened a window before continuing, an Auto Open panel can open the window automatically with a script, instead of asking the user to do it. You can find more about Auto Open panels in Apple Guide Complete.

How do I use pictures in my guide?

Jeanne A. E. DeVoto jaed@jaedworks.com
Copyright © 1996 Jeanne A. E. DeVoto