TweetFollow Us on Twitter

Guide Authoring
Volume Number:12
Issue Number:6
Column Tag:Apple Guide

Apple Guide Authoring Tools

Helping you help users help themselves

By John R. Powers, III, guideWorks, LLC

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

In an earlier article (MacTech Magazine 12.1 [January 1996] 67-70), we reviewed three new books about Apple Guide authoring. Now we’ll focus on the tools for Apple Guide authoring. The January article also contains a brief introduction to Apple Guide in case you need to brush up on your guide terminology.

The original Apple Guide authoring tool is Guide Maker. Two new tools have arrived. They are Danny Goodman’s Apple Guide Starter Kit and StepUp Software’s Guide Composer. We’ll examine all three tools in this review. If you are new to guide authoring, the review may help you to decide where to start. If you’re an old hand at it, the review may help you to decide what to use next.

But first, we will give you a quick overview of the Apple Guide authoring process and how these tools fit in.

The Authoring Process

To create a guide, this is what you usually do:

Task analysis. Identify and articulate the tasks that the user must accomplish.

Instructional design. Specify how the guide will support the user’s tasks.

Content writing. Create the words and images to support the instructional design.

Scripting. Mark up the content with Guide Script. This includes identifying topic areas, index terms, the formatting and sequencing of content, context checking, and automation.

Application integration. Add Apple Guide-specific code to the application. This is an optional step.

Testing. Test guides as a part of the application test suite.

Localization. Adapt the guide to serve an international market.

The authoring tools primarily support content writing and scripting. Guide Maker requires that you write your content and do your scripting with a word processor. Guide Maker takes the word-processing documents and compiles them into a guide. The Starter Kit and Guide Composer replace the word processor with WYSIWYG content entry. Scripting is done by the tool. In addition, the new tools use a new, streamlined version of Guide Maker called Guide Maker Lite for seamless compiling. Figure 1 shows how the tools are used for authoring a guide.

Figure 1. Authoring a guide

Guide Script

Underlying the process is Guide Script. It is a mark-up language that identifies Apple Guide elements, controls content layout, and sequences panels. There are about 100 commands in Guide Script. The language is a combination of definitions, content layout, and panel sequencing. It’s like “HTML meets MPW”. If you are uncomfortable with programming, you may have serious difficulty learning Guide Script. Even scripting-savvy technical writers find the learning curve to be frustratingly steep.

Guide Maker

Guide Maker is the original authoring tool developed by Apple for Apple Guide. It’s five tools in one: build guides, test the look-for search, run and diagnose guides, convert WinHelp to Guide Script, and import/export text for localization. We’ll consider only the “build guides” part here.

This is the granddaddy of all the Apple Guide authoring tools. Guide Maker and its leaner, faster offspring, Guide Maker Lite, are the only tools that can compile guides. And they only compile help content marked up with Guide Script. Until Apple releases a public API for reading and writing guides, we must use Guide Maker or Guide Maker Lite for compilation.

Guide Maker produces the most complete set of Apple Guide features. It’s the reference point for any new authoring tool. So if it does everything, why consider something else? There are lots of reasons, but the biggest one is the fact that you are required to know Guide Script.

Guide Maker itself can make the process difficult. Any error in the Guide Script syntax usually stops compilation. You fix the error and then start compilation from the beginning. There is no incremental compilation. If you have a large guide, compilation can go for many minutes before encountering an error and stopping. This iterative process of compiling, encountering errors, fixing errors, and restarting the compilation is frustrating and time-consuming.

Guide Maker requires text files as its input. This introduces problems in managing the Apple Guide elements and visualizing the final output.

In Apple Guide, everything is related to something else. For example, topic areas are related to topics which are related to sequences which are related to panels. This is shown in simplified form in Figure 2.

Figure 2. One example of the relationship of Apple Guide elements

Each of the four elements - topic area, topic, sequence, and panel - is authored separately and linked to another by referencing its name. It’s up to you to come up with meaningful names and keep track of all the elements. In a reasonably large guide, this can involve many hundreds of elements, a difficult management job for any author. Unfortunately, Guide Maker provides no support for managing all the elements.

Visualizing the final output is another difficulty. Using a word processor, you program the sequence of panels in a topic and specify the formats for how the panel content is to be displayed. When the user views the guide, Apple Guide creates a layout by “flowing” the content into the panel according to your formats. The layout process occurs at display time to allow for automatic adjustment of the panel for localized text. German, for example, requires more panel space than English, to accommodate its larger words. Apple Guide handles this text expansion at runtime. However, a word processor may not display the help content in the same form as Apple Guide. As a result, you must visualize what the help content will look like. If you are used to WYSIWYG writing, you may be frustrated.

Listing 1 shows an example of how a panel is written in Guide Script. The resulting Apple Guide panel is shown in Figure 3.

Listing 1: Apple Guide panel written in Guide Script

<Define Panel> "What is it - panel 1"
<Format> "Tag"
<PICT> 2997, RIGHT
<Format> "Body"
The guideWorks Translator creates a WinHelp project from your Apple Guide 
source files, which you can compile into a WinHelp help file using the 
Windows Help Project Editor.
<End Panel>

Figure 3. The Apple Guide panel created by
the Guide Script in Listing 1

The New Class of Authoring Tools

The Starter Kit and Guide Composer solve authoring problems by using an interface that is almost identical to what the Apple Guide user sees. The tools keep track of the panels, topics, etc., and display them in the correct sequence and layout. Finally, the tools isolate you from the Guide Script by creating it for you.

At any point in entering or editing your help content, you can have the tool create the Guide Script, write an intermediate text file, and compile it with Guide Maker Lite. Guide Maker Lite is included with the tool software, and compilation is automatic. The output from Guide Maker Lite is a production guide.

Apple Guide Starter Kit

The Starter Kit begins with an application that lets you select various guide options and preferences. The application then creates and launches another application for authoring your guide. The derived application becomes the authoring tool for your guide. You use it for entering and editing help content. The content is embedded in the application like a HyperCard stack with an application shell. This produces a very large Starter Kit “document” because of all the application overhead. This has no effect on the size of the compiled guide.

You enter topic areas, topics, and index terms in a window that looks very much like the Apple Guide access window (Figure 4). After entering a topic name, you can enter panel content in a panel-like window (Figure 5). Options are available for adding coach marks, prompts, and “Huh?” sequences. You can reuse existing panels or create new panels. The “Full” and “Tag and Body” panel formats are supported.

A book, Danny Goodman’s Apple Guide Starter Kit, accompanies the software and completely documents the tool. It also provides a lot of useful information on how to author guides and how to modify the Guide Script created by the tool.

Figure 4. Starter Kit topic area window

Figure 5. Starter Kit panel editing window

Guide Composer

Guide Composer begins with a Topic Areas window (Figure 6). You enter topic areas, and topics to go with them. A lot of support is provided for indexing and Look-For. Guide Composer can automatically generate an index list from your content if you wish. This is a great way to start an index list. Guide Composer excludes your Ignore words from the index, but you may still need to touch up the index list after automatic generation. If you prefer, topics can be selectively excluded from automatic indexing and have their index terms assigned manually. Index terms are entered in a very different way than Guide Maker and the Starter Kit. In the other tools, you assign a topic to an index term; in Guide Composer, you do the reverse - when you create a topic in the Topic Area window, you can assign an index term to it. Support for Ignore words, invisible index terms, and synonyms is also provided. The only thing not covered is the stemmer exception list.

Figure 6. Guide Composer topic area window

Panel content is entered in a panel-like window (Figure 7). Options are available for adding coach marks, “Huh?” sequences, Apple Scripts, pictures, and sound. Prompts are selected at the topic level rather than on a panel-by-panel basis as in the Starter Kit. The “Full” and “Tag and Body” panel formats are supported.

Figure 7. Guide Composer panel editing window

Guide Composer also lets you modify a “Standard Defines” file that is automatically included in the compilation. This is handy for modifying many of the defaults and adding your own definitions. Another feature allows you to enter Guide Script directly into the panel. This Guide Script is preserved in the Guide Composer document and included when the guide is compiled. (Guide Script can also be entered directly into the Starter Kit panels, but Guide Composer is more explicit about it.)

The manual describes how to use the tool, but not how to design guides. You should also refer to one of the three Apple Guide books if you want to develop good guides.

Making Choices

What are the advantages to using the Starter Kit or Guide Composer? First of all, you write your help content in the context of what the user sees. You can focus on the content without getting distracted by scripting and layout. Second, you don’t need to learn any Guide Script; the tools create the Guide Script for you. Both tools provide a quick start for guide development. You can start writing useful guides in a matter of days rather than weeks.

What do you give up by using the Starter Kit or Guide Composer? This is a trick question. The answer depends on what you want your guide to do. They are best at creating simple guides using a single-list access window. A full access window is possible, but neither tool provides sufficient support for bullet-proof Look-For searching. If you are willing to learn Guide Script, the tools provide a fast start for a more complete guide. It works like this: Use the tools to produce as complete a guide as you can, then switch to the intermediate Guide Script file to complete the project. Once you start modifying the Guide Script, you can’t go back; any changes made in the intermediate file are not retrofitted into the original document. Every time you make a change in the original document, the intermediate file is re-written from scratch and your changes in the intermediate file are lost.

You will probably want to avoid touching the intermediate Guide Script file. Once you do, it requires manually updating the intermediate file every time you make a change with the tool. Or, you can abandon the original tool and use Guide Maker with the intermediate Guide Script file. This approach has the advantages of a quick start with the Starter Kit or Guide Composer and the completeness of Guide Maker.

Features Supported

An important consideration is the Apple Guide features supported by the tools. There are many features that the new class of tools does not handle. For example, one of Apple Guide’s key features, intelligent assistance, requires context-sensitive branching. The new tools don’t support this feature. Their text editors also don’t support text search-and-replace, a major nuisance when you want to make global changes in your guide. You’ll also need a word processor and Guide Maker if you want to use any hot text. Table 1 shows some key Apple Guide features for the tools.

Apple Guide FeatureGuide Starter Guide
MakerKitComposer
Full access windowYYY
Single-list access windowYYY
Presentation startup windowYNN
Guide menu placementAllAll1 available
Topic AreasYYY
IndexYYY
Look-ForYNY
SequencesAll typesBasic linearBasic linear
Context-sensitive branchingYNN
Create topics and panelsYYY
Style text in panelsYNN
FormatsAll2 available2 available
Coach marksAll2 available2 available
“Huh?” sequences and panelsAll“Huh?” One panel
must be topicper “Huh?”
Drag-and-drop editingNYY
Content search-
and-replaceY (word processor)NN
PromptsAll3 available4 available
Panel content other than textAllNonePICT and
Sound
Hot text in panel contentYNN
ButtonsAll“Huh?” only“Huh?”
and Radio
Source docs file size1X1X1,300K + 1X
Documentation provided554-page 295-page 38-page
bookbookmanual
Guide compilationYYY
Look-For testingYNN
Diagnostic supportYNN
WinHelp conversionYNN
Localization supportYNN
MixinsYNN

Table 1. Apple Guide features supported by the authoring tools

Recommendations

If you want to get the quickest possible start in guide development, choose the Starter Kit. It’s well documented and produces very useful guides quickly. Watch out for the limited Look-For search support. Try it out in your guides and see how you like it. You may find that you need to touch up the Guide Script to get the results you want.

If you want a more full-featured guide, use Guide Composer. It has good support for indexing and Look-For. It also supports more objects and prompts in the panel content. Watch out for the limited help menu support. You can only make guides that go into the “Help” menu position. To put it into one of the other four positions, you’ll need to modify the Guide Script.

If you plan to develop a lot of guides, use Guide Maker. It’s still the most complete tool available. It will take you longer to learn it and to produce your first guide, but you will have much more Apple Guide capability available. You may also want to start with one of the new tools and then switch over to Guide Maker as you build more confidence.

Where to get the tools

Guide Maker accompanies the book Apple Guide Complete: Designing and Developing Onscreen Assistance by Apple Developer Press. Software updates of Guide Maker and Guide Maker Lite are available from the Apple and guideWorks Web sites.

The Starter Kit accompanies the book Danny Goodman’s Apple Guide Starter Kit. A demo version of the Starter Kit can be downloaded from the guideWorks Web site. (Both books are reviewed in the January article referred to above.)

Guide Composer is published by StepUp Software (214-360-9301). A demo version of Guide Composer can be downloaded from the StepUp or guideWorks Web site.

stepup@onramp.net

http://rampages.onramp.net/~stepup/

The guideWorks Web site has lots of information about Apple Guide and Guide Maker. It also has demo versions of the Starter Kit and Guide Composer for downloading.

http://www.guideworks.com

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Apple macOS Sierra 10.12.6 - The latest...
With Apple macOS Sierra, Siri makes its debut on Mac, with new features designed just for the desktop. Your Mac works with iCloud and your Apple devices in smart new ways, and intelligent... Read more
VMware Fusion 8.5.8 - Run Windows apps a...
VMware Fusion 8 and Fusion 8 Pro--the latest versions of its virtualization software for running Windows on a Mac without rebooting--include full support for Windows 10, OS X El Capitan, and the... Read more
Apple Safari 10.1.2 - Apple's Web b...
Note: The direct download link is currently unavailable. It is available in the OS X 10.12.6 release, as well as in the Apple Security Updates. Apple Safari is Apple's web browser that comes with OS... Read more
OnyX 3.2.7 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Postbox 5.0.16 - Powerful and flexible e...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
DiskCatalogMaker 7.1.1 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
ExpanDrive 6.0.12 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
SteerMouse 5.1.3 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. It also supports Apple Mighty Mouse very well. SteerMouse can assign various functions to buttons that Apple's software does not allow,... Read more
Mac DVDRipper Pro 7.0.1 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
Sandvox 2.10.9 - Easily build eye-catchi...
Sandvox is for Mac users who want to create a professional looking website quickly and easily. With Sandvox, you don't need to be a Web genius to build a stylish, feature-rich, standards-compliant... Read more

Latest Forum Discussions

See All

Realpolitiks Mobile (Games)
Realpolitiks Mobile 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: PLEASE NOTE: The game might not work properly on discontinued 1GB of RAM devices (iPhone 5s, iPhone 6, iPhone 6 Plus, iPad... | Read more »
Layton’s Mystery Journey (Games)
Layton’s Mystery Journey 1.0.0 Device: iOS Universal Category: Games Price: $15.99, Version: 1.0.0 (iTunes) Description: THE MUCH-LOVED LAYTON SERIES IS BACK WITH A 10TH ANNIVERSARY INSTALLMENT! Developed by LEVEL-5, LAYTON’S... | Read more »
Full Throttle Remastered (Games)
Full Throttle Remastered 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Originally released by LucasArts in 1995, Full Throttle is a classic graphic adventure game from industry legend Tim... | Read more »
Stunning shooter Morphite gets a new tra...
Morphite is officially landing on iOS in September. The game looks like the space shooter we've been needing on mobile, and we're going to see if it fits the bill quite shortly. The game's a collaborative effort between Blowfish Studios, We're Five... | Read more »
Layton's Mystery Journey arrives to...
As you might recall, Layton's Mystery Journey is headed to iOS and Android -- tomorrow! To celebrate the impending launch, Level-5's released a new trailer, complete with an adorable hamster. [Read more] | Read more »
Sidewords (Games)
Sidewords 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Grab a cup of coffee and relax with Sidewords. Sidewords is part logic puzzle, part word game, all original. No timers. No... | Read more »
Noodlecake Games' 'Leap On!...
Noodlecake Games is always good for some light-hearted arcade fun, and its latest project, Leap On! could carry on that tradition. It's a bit like high stakes tetherball in a way. Your job is to guide a cute little blob around a series of floating... | Read more »
RuneScape goes mobile later this year
Yes, RuneScape still exists. In fact, it's coming to iOS and Android in just a few short months. Jagex, creators of the hit fantasy MMORPG of yesteryear, is releasing RuneScape Mobile and Old School RuneScape for mobile devices, complete with... | Read more »
Crash of Cars wants you to capture the c...
Crash of Cars is going full on medieval in its latest update, introducing castles and all manner of new cars and skins fresh from the Dark Ages. The update introduces a new castle-themed map (complete with catapults) and a gladiator-style battle... | Read more »
Golf Clash guide: How to rise through th...
For a little game as cartoony and colorful as Golf Clash, competition can be quite fierce. You need to be on top of your game and have the best equipment possible if you want to get very far. True success is measured by both player skill and the... | Read more »

Price Scanner via MacPrices.net

13-inch 2.3GHz Silver MacBook Pro on sale for...
B&H Photo has the new 2017 13″ 2.3GHz/256GB Silver MacBook Pro (MPXU2LL/A) on sale for $1399 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Apple Tackles Distracted Driving With iOS 11...
One of the most important new features coming in iOS 11 is Do Not Disturb while driving, intended to help drivers stay more focused on the road. With Do Not Disturb while driving, your iPhone can... Read more
iMazing Mini for Mac: Free Automatic and Priv...
Geneva, Switzerland-based indie developer DigiDNA has released iMazing Mini, their free macOS utility designed to automatically back up iOS devices over any local Wi-Fi network. The app offers users... Read more
Clearance 2016 13-inch MacBook Airs, Apple re...
Apple dropped prices recently on Certified Refurbished 2016 13″ MacBook Airs, with models now available starting at $809. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
9.7-inch 2017 iPads available for $299, save...
B&H Photo has 2017 9.7″ 32GB WiFi iPads on sale for $30 off MSRP for a limited time. Shipping is free, and pay sales tax in NY & NJ only: – 32GB iPad WiFi: $299, $30 off Read more
Welcome to the new MacPrices.net!
Welcome to the newly redesigned MacPrices.net! MacPrices has been comprehensively redesigned from the ground up over the past couple of weeks. The new design is cleaner, with less clutter, minimal... Read more
Clearance iMacs available for up to $370 off...
B&H Photo has clearance 21″ and 27″ Apple iMacs available for up to $370 off original MSRP, each including free shipping plus NY & NJ sales tax only: – 27″ 3.3GHz iMac 5K: $1929 $370 off... Read more
Sale! 15-inch 2.8GHz MacBook Pros for $100 of...
B&H Photo has the new 2017 15″ 2.8GHz Touch Bar MacBook Pros on sale for $100 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray: $... Read more
New 27-inch 3.5GHz iMac on sale for $1899, sa...
Amazon has the new 27″ 3.5GHz iMac (MNEA2LL/A) on sale for $1899.99 including free shipping. Their price is $100 off MSRP, and it’s currently the lowest price available for this model. Read more
Clearance iMacs, Apple refurbished, available...
Apple dropped prices recently on previous-generation Certified Refurbished 2015 21″ & 27″ iMacs, with models now available starting at $849. Apple’s one-year warranty is standard, and shipping is... Read more

Jobs Board

Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
*Apple* Customer Experience (ACE) Leader - A...
…management to deliver on business objectivesTraining partner store staff on Apple products, services, and merchandising guidelinesCoaching partner store staff on Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
*Apple* Solutions Consultant - Apple Inc. (U...
…about helping others on a team while also delighting customers? As an Apple Solutions Consultant (ASC), you will discover customers needs and help connect them Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.