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

 
AAPL
$116.47
Apple Inc.
+0.16
MSFT
$47.98
Microsoft Corpora
-0.72
GOOG
$537.50
Google Inc.
+2.67

MacTech Search:
Community Search:

Software Updates via MacUpdate

Cobook 3.0.7 - Intelligent address book....
Cobook Contacts is an intuitive, engaging address book. Solve the problem of contact management with Cobook Contacts and its simple interface and powerful syncing and integration possibilities.... Read more
StatsBar 1.9 - Monitor system processes...
StatsBar gives you a comprehensive and detailed analysis of the following areas of your Mac: CPU usage Memory usage Disk usage Network and bandwidth usage Battery power and health (MacBooks only)... Read more
Cyberduck 4.6 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Maya 2015 - Professional 3D modeling and...
Maya is an award-winning software and powerful, integrated 3D modeling, animation, visual effects, and rendering solution. Because Maya is based on an open architecture, all your work can be scripted... Read more
Evernote 6.0.1 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
calibre 2.11 - Complete e-library manage...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more
Herald 5.0.1 - Notification plugin for M...
Note: Versions 2.1.3 (for OS X 10.7), 3.0.6 (for OS X 10.8), and 4.0.8 (for OS X 10.9) are no longer supported by the developer. Herald is a notification plugin for Mail.app, Apple's Mac OS X email... Read more
Firetask 3.7 - Innovative task managemen...
Firetask uniquely combines the advantages of classical priority-and-due-date-based task management with GTD. Stay focused and on top of your commitments - Firetask's "Today" view shows all relevant... Read more
TechTool Pro 7.0.6 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PhotoDesk 3.0.1 - Instagram client for p...
PhotoDesk lets you view, like, comment, and download Instagram pictures/videos! (NO Uploads! / Image Posting! Instagram forbids that! AND you *need* an *existing* Instagram account). But you can do... Read more

Latest Forum Discussions

See All

Ubisoft Gives Everyone Two New Ways to E...
Ubisoft Gives Everyone Two New Ways to Earn In-Game Stuff for Far Cry 4 Posted by Jessica Fisher on November 21st, 2014 [ permalink ] | Read more »
Golfinity – Tips, Tricks, Strategies, an...
Dig this: Would you like to know what we thought of being an infinite golfer? Check out our Golfinity review! Golfinity offers unlimited ways to test your skills at golf. Here are a few ways to make sure your score doesn’t get too high and your... | Read more »
Dark Hearts, The Sequel to Haunting Meli...
Dark Hearts, The Sequel to Haunting Melissa, is Available Now Posted by Jessica Fisher on November 21st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Meowza! Toyze Brings Talking Tom to Life...
Meowza! | Read more »
Square Enix Announces New Tactical RPG f...
Square Enix Announces New Tactical RPG for Mobile, Heavenstrike Rivals. Posted by Jessica Fisher on November 21st, 2014 [ permalink ] With their epic stories and gorgeous graphics, | Read more »
Quest for Revenge (Games)
Quest for Revenge 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: The great Kingdom of the west has fallen. The gods ignore the prayers of the desperate. A dark warlord has extinguished... | Read more »
Threadz is a New Writing Adventure for Y...
Threadz is a New Writing Adventure for You and Your Friends Posted by Jessica Fisher on November 21st, 2014 [ permalink ] In the tradition of round-robin storytelling, | Read more »
SteelSeries Stratus XL Hardware Review
Made by: SteelSeries Price: $59.99 Hardware/iOS Integration Rating: 4 out of 5 stars Usability Rating: 4.5 out of 5 stars Reuse Value Rating: 4.25 out of 5 stars Build Quality Rating: 4.5 out of 5 stars Overall Rating: 4.31 out of 5 stars | Read more »
ACDSee (Photography)
ACDSee 1.0.0 Device: iOS iPhone Category: Photography Price: $1.99, Version: 1.0.0 (iTunes) Description: Capture, perfect, and share your photos with ACDSee. The ACDSee iPhone app combines an innovative camera, a powerful photo... | Read more »
ProTube for YouTube (Entertainment)
ProTube for YouTube 2.0.2 Device: iOS Universal Category: Entertainment Price: $1.99, Version: 2.0.2 (iTunes) Description: ProTube is the ultimate, fully featured YouTube app. With it's highly polished design, ProTube offers ad-free... | Read more »

Price Scanner via MacPrices.net

CEA Study Finds More People Recycling Electro...
A new study by the Consumer Electronics Association (CEA) finds that electronics recycling receives the continued and growing support of consumers. According to the CEA,s Recycling and Reuse Study,... Read more
15″ 2.2GHz Retina MacBook Pro on sale for $17...
 B&H Photo has the 2014 15″ 2.2GHz Retina MacBook Pro on sale today for $1749. Shipping is free, and B&H charges NY sales tax only. B&H will also include free copies of Parallels Desktop... Read more
27-inch 3.5GHz 5K iMac in stock today and on...
 B&H Photo has the new 27″ 3.5GHz 5K iMac in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price available... Read more
21-inch 1.4GHz iMac on sale for $979, save $1...
B&H Photo has the new 21″ 1.4GHz iMac on sale for $979.99 including free shipping plus NY sales tax only. Their price is $120 off MSRP. B&H will also include free copies of Parallels Desktop... Read more
13-inch 1.4GHz/256GB MacBook Air on sale for...
B&H Photo has lowered their price on the 13″ 1.4GHz/256GB MacBook Air to $1059.99 including free shipping plus NY sales tax only. Their price is $140 off MSRP, and it’s the lowest price for this... Read more
Save up to $400 with Apple refurbished 2014 1...
The Apple Store has restocked Apple Certified Refurbished 2014 15″ Retina MacBook Pros for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and shipping... Read more
New 13-inch 1.4GHz MacBook Air on sale for $8...
 Adorama has the 2014 13″ 1.4GHz/128GB MacBook Air on sale for $899.99 including free shipping plus NY & NJ tax only. Their price is $100 off MSRP. B&H Photo has the 13″ 1.4GHz/128GB MacBook... Read more
Apple Expected to Reverse Nine-Month Tablet S...
Apple and Samsung combined accounted for 62 percent of the nearly 36 million branded tablets shipped in 3Q 2014, according to early vendor shipment share estimates from market intelligence firm ABI... Read more
Stratos: 30 Percent of US Smartphone Owners t...
Stratos, Inc., creator of the Bluetooth Connected Card Platform, has announced results from its 2014 Holiday Mobile Payments Survey. The consumer survey found that nearly one out of three (30 percent... Read more
2014 1.4GHz Mac mini on sale for $449, save $...
 B&H Photo has lowered their price on the new 1.4GHz Mac mini to $449.99 including free shipping plus NY tax only. Their price is $50 off MSRP, and it’s the lowest price available for this new... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC)- Retail S...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Store Leader Program - College Gradu...
Job Description: Job Summary As an Apple Store Leader Program agent, you can continue your education as you major in the art of leadership at the Apple Store. You'll Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.