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

Adobe After Effects CC 2018 16.1.3 - Cre...
After Effects CC 2018 is available as part of Adobe Creative Cloud for $52.99/month (or $20.99/month for a single app license). The new, more connected After Effects CC 2018 can make the impossible... Read more
Adobe Audition CC 2019 12.1.4 - Professi...
Audition CC 2019 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Audition customer). Adobe Audition CC 2019 empowers you to create and... Read more
Adobe Premiere Pro CC 2019 13.1.5 - Digi...
Premiere Pro CC 2019 is available as part of Adobe Creative Cloud for as little as $52.99/month. The price on display is a price for annual by-monthly plan for Adobe Premiere Pro only Adobe Premiere... Read more
Navicat Premium Essentials 12.1.25 - Pro...
Navicat Premium Essentials is a compact version of Navicat which provides basic and necessary features you will need to perform simple administration on a database. It supports the latest features... Read more
Sketch 58 - Design app for UX/UI for iOS...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more
ClipGrab 3.8.5 - Download videos from Yo...
ClipGrab is a free downloader and converter for YouTube, Vimeo, Facebook and many other online video sites. It converts downloaded videos to MPEG4, MP3 or other formats in just one easy step Version... Read more
Dash 4.6.6 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
FotoMagico 5.6.8 - Powerful slideshow cr...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Civilization VI 1.2.4 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
Skype 8.52.0.138 - Voice-over-internet p...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more

Latest Forum Discussions

See All

Lots of premium games are going free (so...
You may have seen over the past couple weeks a that a bunch of premium games have suddenly become free. This isn’t a mistake, nor is it some last hurrah before Apple Arcade hits, and it’s important to know that these games aren’t actually becoming... | Read more »
Yoozoo Games launches Saint Seiya Awaken...
If you’re into your anime, you’ve probably seen or heard of Saint Seiya. Based on a shonen manga by Masami Kurumada, the series was massively popular in the 1980s – especially in its native Japan. Since then, it’s grown into a franchise of all... | Read more »
Five Nights at Freddy's AR: Special...
Five Nights at Freddy's AR: Special Delivery is a terrifying new nightmare from developer Illumix. Last week, FNAF fans were sent into a frenzy by a short teaser for what we now know to be Special Delivery. Those in the comments were quick to... | Read more »
Rush Rally 3's new live events are...
Last week, Rush Rally 3 got updated with live events, and it’s one of the best things to happen to racing games on mobile. Prior to this update, the game already had multiplayer, but live events are more convenient in the sense that it’s somewhat... | Read more »
Why your free-to-play racer sucks
It’s been this way for a while now, but playing Hot Wheels Infinite Loop really highlights a big issue with free-to-play mobile racing games: They suck. It doesn’t matter if you’re trying going for realism, cart racing, or arcade nonsense, they’re... | Read more »
Steam Link Spotlight - The Banner Saga 3
Steam Link Spotlight is a new feature where we take a look at PC games that play exceptionally well using the Steam Link app. Our last entry talked about Terry Cavanaugh’s incredible Dicey Dungeons. Read about how it’s a great mobile experience... | Read more »
Combo Quest (Games)
Combo Quest 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Combo Quest is an epic, time tap role-playing adventure. In this unique masterpiece, you are a knight on a heroic quest to retrieve... | Read more »
Hero Emblems (Games)
Hero Emblems 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ** 25% OFF for a limited time to celebrate the release ** ** Note for iPhone 6 user: If it doesn't run fullscreen on your device... | Read more »
Puzzle Blitz (Games)
Puzzle Blitz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Puzzle Blitz is a frantic puzzle solving race against the clock! Solve as many puzzles as you can, before time runs out! You have... | Read more »
Sky Patrol (Games)
Sky Patrol 1.0.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.1 (iTunes) Description: 'Strategic Twist On The Classic Shooter Genre' - Indie Game Mag... | Read more »

Price Scanner via MacPrices.net

$250 prepaid Visa card with any Apple iPhone,...
Xfinity Mobile will include a free $250 prepaid Visa card with the purchase of any new iPhone, new line activation, and transfer of phone number to Xfinity Mobile. Offer is valid through October 27,... Read more
Sprint is offering the 64GB Apple iPhone 11 P...
Sprint has the new 64GB iPhone 11 Pro available for $12.50 per month for new customers with an eligible trade-in in of iPhone 7 or newer. That’s down from their standard monthly lease of $41.67. The... Read more
Final week: Apple’s 2019 Back to School Promo...
Purchase a new Mac using Apple’s Education discount, and take up to $400 off MSRP. All teachers, students, and staff of any educational institution with a .edu email address qualify for the discount... Read more
Save $30 on Apple’s AirPods at these reseller...
Amazon is offering discounts on new 2019 Apple AirPods ranging up to $30 off MSRP as part of their Labor Day sale. Shipping is free: – AirPods with Charging Case: $144.95 $15 off MSRP – AirPods with... Read more
Preorder your Apple Watch Series 5 today at A...
Amazon has Apple Watch Series 5 GPS models available for preorder and on sale today for $15 off Apple’s MSRP. Shipping is free and starts on September 20th: – 40mm Apple Watch Series 5 GPS: $384.99 $... Read more
21″ iMacs on sale for $100 off Apple’s MSRP,...
B&H Photo has new 21″ Apple iMacs on sale for $100 off MSRP with models available starting at $999. These are the same iMacs offered by Apple in their retail and online stores. Overnight shipping... Read more
2018 4 and 6-Core Mac minis on sale today for...
Apple resellers are offering new 2018 4-Core and 6-Core Mac minis for $100-$150 off MSRP for a limited time. B&H Photo has the new 2018 4-Core and 6-Core Mac minis on sale for up to $150 off... Read more
Save $150-$250 on 10.2″ WiFi + Cellular iPads...
Verizon is offering $150-$250 discounts on Apple’s new 10.2″ WiFi + Cellular iPad with service. Buy the iPad itself and save $150. Save $250 on the purchase of an iPad along with an iPhone. The fine... Read more
Apple continues to offer 13″ 2.3GHz Dual-Core...
Apple has Certified Refurbished 2017 13″ 2.3GHz Dual-Core non-Touch Bar MacBook Pros available starting at $1019. An standard Apple one-year warranty is included with each model, outer cases are new... Read more
Apple restocks 2018 MacBook Airs, Certified R...
Apple has restocked Certified Refurbished 2018 13″ MacBook Airs starting at only $849. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is shipped free. The... Read more

Jobs Board

Student Employment (Blue *Apple* Cafe) Spri...
Student Employment (Blue Apple Cafe) Spring 2019 Penn State University Campus/Location: Penn State Brandywine Campus City: Media, PA Date Announced: 12/20/2018 Date Read more
Geek Squad *Apple* Master Consultation Agen...
**732907BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 000360-Williston-Store Read more
*Apple* Mobile Master - Best Buy (United Sta...
**728519BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 000853-Jackson-Store **Job Description:** **What does a Best Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**733006BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Location Number:** 000865-Conroe-Store **Job Description:** At Best Buy, our Read more
*Apple* Mobility Pro-Store 149 - Best Buy (U...
**731985BR** **Job Title:** Apple Mobility Pro-Store 149 **Job Category:** Store Associates **Location Number:** 000149-Towson-Store **Job Description:** At Best Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.