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

Together 3.4.6 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Smart storage. With simple drag-and-drop functionality,... Read more
Monosnap 3.1.0 - Versatile screenshot ut...
Monosnap lets you capture screenshots, share files, and record video and .gifs! Capture: Capture full screen, just part of the screen, or a selected window Make your crop area pixel perfect with... Read more
Cocktail 8.5.1 - General maintenance and...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Vienna 3.0.6 :5eaf312: - RSS and Atom ne...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
Kodi 15.1.rc1 - Powerful media center to...
Kodi (was XBMC) is an award-winning free and open-source (GPL) software media player and entertainment hub that can be installed on Linux, OS X, Windows, iOS, and Android, featuring a 10-foot user... Read more
Bookends 12.5.8 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Access the power of Bookends directly from Mellel, Nisus Writer Pro, or MS Word (... Read more
Chromium 44.0.2403.125 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 44.0.2403.125: This release contains a number... Read more
iMazing 1.2.2 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Audio Hijack 3.2.0 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
FontExplorer X Pro 5.0.1 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more

Card King: Dragon Wars - Tips, Tricks an...
[Read more] | Read more »
Pac-Man Championship Edition DX has brou...
Bandai Namco has released Pac-Man Championship Edition DX on iOS and Android, which features the classic arcade gameplay that we've all grown to love. Pac-Man Championship Edition DX can be enjoyed in much shorter bursts than the arcade versions... | Read more »
Cosmonautica (Games)
Cosmonautica 1.1 Device: iOS Universal Category: Games Price: $6.99, Version: 1.1 (iTunes) Description: Cast off! Are you ready for some hilarious adventures in outer space? | Read more »
Rescue humanity from a Demon horde in An...
Angel Stone is Fincon's follow up to the massively successful Hello Hero and is out now on iOS and Android. You play as a member of The Resistance, a group of mighty human warriors who have risen up in defiance of the Demon horde threatening to... | Read more »
Gallery Doctor (Photography)
Gallery Doctor 1.0 Device: iOS iPhone Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Free up valuable iCloud and iPhone storage with Gallery Doctor, the only iPhone cleaner that automatically identifies the... | Read more »
You Against Me (Games)
You Against Me 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: A simple game… You. Me. Claim, steal, lock, score, win! | Read more »
Yep, it's True - Angry Birds 2 is O...
The not exactly rumors were true and the birds are back. Angry Birds 2 has come to the App Store and the world will... well I suppose it'll still be the same, but now we have more bird-flinging options! [Read more] | Read more »
You Could Design Your Own Card for Chain...
If you've ever wanted to create your own item, weapon, trap, or even monster for Chainsaw Warrior: Lords of the Night, this is your chance. Auroch Digital is currently holding a contest so that fans can fight to the death (not really) to see which... | Read more »
Bitcoin Billionaire is Going Back in Tim...
If you thought you managed to buy everything there is to buy in Bitcoin Billionaire and make all the money, well you though wrong. Those of you who made it far enough might remember investing in time travel - and it looks like that investment is... | Read more »
Domino Drop (Games)
Domino Drop 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Domino Drop is a delightful new puzzle game with dominos and gravity!Learn how to play it in a minute, master it day by day.Your... | Read more »

Price Scanner via MacPrices.net

27-inch 3.5GHz 5K iMac on sale for $81 off MS...
Adorama has the 27″ 3.5GHz 5K iMac on sale for $2218, $81 off MSRP, including a free copy of Apple’s 3-Year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax in NY & NJ... Read more
Back-to-School with Tablet and Smartphone Acc...
Belkin helps you prepare for the coming school year with a wide variety of the latest mobile and tablet accessories to outfit both grade school and college students. The line-up includes charging... Read more
11-inch MacBook Airs on sale for $100 off MSR...
Best Buy has 11-inch MacBook Airs on sale for $100 off MSRP. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - 11″ 1.6GHz... Read more
iPad Air 2 on sale for up to $100 off MSRP
Best Buy has iPad Air 2s on sale for up to $100 off MSRP on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale prices available for online... Read more
Sale! 13-inch MacBook Pros on sale for $100 o...
B&H Photo has 13″ MacBook Pros on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.5GHz/500GB MacBook Pro: $999.99 save $100 - 13″ 2.7GHz/128GB Retina... Read more
Sale! Save $100 on 13-inch MacBook Airs this...
B&H Photo has the 13″ 1.6GHz/128GB MacBook Air on sale for $899.99 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model.... Read more
Worldwide Tablet Market Decline Continues, Ap...
The worldwide tablet market declined -7.0% year-over-year in the second quarter of 2015 (2Q15) with shipments totaling 44.7 million units according to preliminary data from the International Data... Read more
TP-LINK TL-PA8030P KIT Powerline Featuring Ho...
Consumer and business networking products provider TP-LINK is now shipping its TL-PA8030P KIT AV1200 3-Port Gigabit Passthrough Powerline Starter Kit that expands your home’s network over its... Read more
Apple refurbished iPad Air 2s available for u...
The Apple Store has Apple Certified Refurbished iPad Air 2s available for up to $140 off the price of new models. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB... Read more
Updated Apple iPad Price Trackers
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers. Read more

Jobs Board

*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
Infrastructure Engineer - *Apple* /Mac - Hil...
Infrastructure Engineer - Apple /Mac Job Code: 1608 # of openings: 1 Description Our fortune 500 client is looking to hire an experienced Infrastructure Engineer to join Read more
Executive Administrative Assistant, *Apple*...
…supporting presentation development for senior leadership. * User experience with Apple hardware and software is preferred. Additional Requirements The following list Read more
*Apple* Bus Company is now hirin - Apple Bus...
Apple Bus Company is now hiring school bus drivers in the Pettis County area. Class B CDL preferred. Free training provided. No nights or weekends required. Flexible Read more
*Apple* Certified Mac Technician - Updated 6...
…and friendly, hands-on technical support to customers troubleshooting and repairing Apple /Mac products with courtesy, speed and skill. Use your problem-solving skills Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.