guideWorks, LLC Apple Guide FAQ




Guide Writing Style
How do I . . . Where . . .

How do I decide whether to use Apple Guide for my project?

Apple Guide is best at providing interactive, step-by-step, task-based instructions. Apple Guide will fit your documentation needs well if your documentation

You can also use Apple Guide as a hypertext reference engine, although this type of documentation doesn't really take advantage of many of Apple Guide's strengths (such as coaching and context-checking). Apple Guide is best used for reference material that is brief and which users frequently look up while they're at the computer. Syntax cheat-sheets for programming or scripting languages, power-user shortcuts, and quick FAQs are all appropriate for Apple Guide.

There are a few things Apple Guide is not really appropriate for:


How do I create an Apple Guide if I'm not a programmer?

There are a number of tools, such as Guide Composer, the Apple Guide Starter Kit, and AG Author, that you can use to create guides without knowing GuideScript (AppleGuide's script language). These tools serve as a front end: you type in your text and specify certain aspects of how you want the guide to behave, and the tool generates the appropriate GuideScript code, ready to be compiled into a guide.

Because these tools don't offer as much power and flexibility as you can get from working directly with the GuideScript source, you may decide to collaborate with an experienced scripter. The scripter can either work with you from the beginning of guide development, taking your text and transforming it into GuideScript code, or take a preliminary guide you've created with one of the tools above and add advanced features to it.

While you don't need to be a programmer to write a successful guide, you should be aware of the general outlines of how Apple Guide works "under the hood"; this way, you have some idea of what is and is not possible for your guide to accomplish. You also need to know a little about how your guide works with the program it documents. There are a number of enhancements the application programmer can provide to make your guide work better - context sensitivity, custom coachmarks, and custom context checks - and your ability to work with the application programmers in these areas will result in a better guide, as well as less hair-pulling during guide development.


How do I create sidebars and notes in a guide?

Sidebars, notes, and other information that isn't necessary to complete the task at hand can be placed in a separate sequence. The scripter uses the LaunchNewSequenceNewWindow event to open a second Apple Guide window that contains this sequence. The user can bring up the extra information if desired, but isn't distracted by it while focused on a specific task. (Since space in an Apple Guide panel is more limited than space on a page, and reading text from a screen is physically more difficult than reading it in print, it's usually not appropriate to place ancillary information in the panel itself, the way you might in a printed book.)

You can display such information in a number of ways:

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:

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

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?


You can include a picture anywhere in a panel window by using the <PICT> command. (There's no way to include pictures in the access window or in the title area of a panel window.) The easiest way to include a picture is to put the <PICT> command on a line by itself wherever you want the picture to appear.

(It's possible to place a small picture in the middle of a text line by inserting enough spaces to leave room for the picture and using the Point() function with the <PICT> command to place the picture in the gap you've made in the text. However, because this method depends on the gap appearing at a particular hard-coded location on the panel, it can be a problem to maintain; if the surrounding text is rewritten or translated, the gap will move, and you'll need to re-compute the point where the picture should be placed.)

As with any special effect, ask yourself whether this picture is necessary. Does it enhance the user's understanding, provide help with navigation, or serve another useful purpose? Or is it there just to look nice? Remember that someone using your guide is probably focused on completing a task or finding a particular bit of information, not on reading the guide for its own sake; any visual elements that distract such a user's attention are likely to be annoying.

If possible, avoid placing pictures of interface elements (such as buttons, palettes, or menus) in the panel window. Since their attention is on the guide window, users sometimes get confused and click these pictures instead of the actual interface elements. If you want to point out an interface element to a user, it's better to use a coachmark instead.

If you do need to include such a picture, you can use graphic techniques to make it more obvious that this is not an actual user-interface element: a gray drop shadow, a torn-off edge, or something similar. This makes it less likely for a user to confuse the picture with the actual interface element.


Where can I find examples and help?


You may find these resources helpful when writing a guide:




Thanks to Jeanne A. E. DeVoto for her contributions to these FAQ.
Compilation copyright ©1997 guideWorks, LLC -- Last updated: 970402 GPB