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

Latest Forum Discussions

See All

Can PokeMatch help you find love with Po...
The unofficial Pokemon GO companion app space has exploded almost as fast as the game itself over the last few weeks. Aspiring app developers, many of them working solo, have given us apps that locate Pokemon, keep track of the server status, and... | Read more »
How to get started with Prisma
If there's one thing people like to do more than taking pictures with their smartphones, it's tinkering with those photos in some way. Numerous apps have sprung up over the last several years that allow you to use filters and special effects to... | Read more »
6 Pokemon GO updates you can expect, acc...
Pokemon GO had a scheduled appearance at this year's San Diego Comic-Con for a while, but it was only relatively close to the show that it was upgraded to a spot in Hall H. That's the biggest venue at SDCC, one usually reserved for the largest... | Read more »
How to evolve Eevee in Pokemon GO
By now, almost everyone should be hip to how to evolve Pokemon in Pokemon GO (and if not, there's a guide for that). Just gather enough candy of the appropriate type, feed them all to the Pokemon, and evolution happens. It's a miracle that would... | Read more »
CSR Racing 2: Guide to all game modes
It might not seem like there are all that many ways to go fast in a straight line, but CSR Racing 2 begs to differ. [Read more] | Read more »
Bulb Boy (Games)
Bulb Boy 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Multi-award winning 2D point & click horror adventure about a boy with a glowing head. | Read more »
5 top free emoji keyboard apps
If we're not at peak emoji yet as a society, it feels like we definitely should be. The emoji concept has gone far beyond what anyone in Japan could have envisioned when the people there unleashed it on an unsuspecting world, but the West has... | Read more »
How to unlock more characters in Disney...
One of the big charms of Disney Emoji Blitz is seeing a wide variety of beloved Disney and Pixar characters transformed into smiling emojis. Even someone like the sneaky Randall from Monsters Inc., who probably never cracked a smile on film, is... | Read more »
Cubway (Games)
Cubway 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Cubway is a journey with an abstract story of lifecycle of rebirth, called Samsara. Guide the cube through the long way full of dangers... | Read more »
Colorcube (Games)
Colorcube 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Turn pieces and blend colours in this minimal yet visually stunning puzzler.Over 200 handcrafted and challenging levels. Features... | Read more »

Price Scanner via MacPrices.net

External Keyboard Innovations For iPad Pro (1...
I’m an input device aficionado. With non-touchscreen computers, which includes all Macs, the keyboard and mouse or trackpad are the tactile points of interface between user and machine, and the... Read more
GSK Rheumatoid Arthritis Study Leverages iPho...
Global healthcare products company GlaxoSmithKline (GSK) says that since 2014 they have begun transforming the way they conduct research, by leveraging state-of-the-art digital technologies — a... Read more
Clearance 12-inch Retina MacBooks, Apple refu...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available starting at $929. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1199 $100 off MSRP - 13″ 2.7GHz/... Read more
13-inch 1.6GHz/128GB MacBook Air on sale for...
Amazon has the 13″ 1.6GHz/128GB MacBook Air on sale for $200 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $799.99 $200 off MSRP Their price is the... Read more
13-inch 1.6GHz/256GB MacBook Air on sale for...
Amazon has the 13″ 1.6GHz/256GB MacBook Air on sale for $200 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/256GB MacBook Air (sku MMGG2LL/A): $999.99 $200 off MSRP Their price is the... Read more
Free iOS Business App notably* Helps Service...
PayStudio Inc. has introduced their new business app notably* 1.0, developed for iPhone and iPod touch. notably* was specifically developed to help service and trade professionals go digital and... Read more
27-inch iMacs on sale for $200 off MSRP
Amazon has 27″ iMacs on sale for $200 off MSRP including free shipping: - 27″ 3.3GHz iMac 5K: $2099 $200 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1799.99 $200 off MSRP - 27″ 3.2GHz/1TB HD iMac 5K... Read more
Mac Pros on sale for $200 off MSRP
B&H Photo has Mac Pros on sale for $200 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3799, $200... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The following... Read more

Jobs Board

*Apple* Retail - Multiple Positions, Willow...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Evangelist - JAMF Software (United S...
The Apple Evangelist is responsible for building and cultivating strategic relationships with Apple 's small and mid-market business development field teams. This Read more
*Apple* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
*Apple* Professional Learning Specialist - A...
Job Summary The Apple Professional Learning Specialist is a full-time position for one year with Apple in the Phoenix, AZ area. This position requires a high Read more
*Apple* Picker - Apple Hill Orchard (United...
Apple Hill Orchard, Co. Rte. 21,Whitehall, NY 9/7/16-10/228/16. Pick fresh market or processing apples Productivity of 60 boxes and 80 boxes processing fruit per Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.