Jonathan Price
The Communication Circle, LLC


When the Mac OS Help team in Apple’s production documentation group was planning the Help for the forthcoming Mac OS X, they confronted the possibility that they might not get everything documented correctly at first release. How could they update the info on a regular basis?

Traditional help gets stamped on the CD and stays put, glued to the software until the user finally installs an update. Old, inaccurate, or incomplete articles often persist in the field for years—and customers who get confused or disappointed by the manual or help system may get frustrated and demand expensive phone support. If only the customers had access to the new versions of help, they could avoid spending time on the phone—and the company could save money.

The team decided to update their documentation continuously—over the Web. Gordon Meyer, documentation manager and interaction designer for Apple Help, the help system built into Mac OS X, says that “To do this, we decided to unbury our topics. That is, we would do one topic per page.” In that way, a writer could laser in on the article needing corrections without disturbing any other information. And users could uncover just the information they needed without being distracted by similar or vaguely related material.

The decision to display only one topic per page meant the team could simplify their page layout—and their information structure. “We knew that we needed a completely new look for the help, but we hadn’t yet settled on what that would be. So we decided to completely separate the information from its appearance. Authoring in a database allowed us to do that quite handily.”

From the database to the customer

The team turned to FileMaker Pro, database software from an Apple subsidiary. They created a form for writers to fill in and built a work flow around the output from the database. At first, the team used AppleScript to extract the data from FileMaker Pro and wrap it in HTML. “Today, though, we export from FileMaker using one of the preset XML DTDs that come with the software. We then use a little post-processing and Apache’s Xalan to transform the FileMaker Pro export into several hundred HTML files.”

But how could the team get new articles out to the users? The team created a Help Viewer to display any application’s help and programmed the viewer to look out on the Web for an updated index to the topics. Meyer says, “When a user opens Help, the Help Viewer checks to see if a newer search index is available. And if it is, it is downloaded and overrides the search index that was initially included with the help. Each “help book” can specify its own location (URL) where the Help Viewer can look for newer versions of the index and help content. This all happens automatically for users who are connected to the Internet while they’re using the Help.”

For each product’s help, the index is only a couple hundred k—often a lot less. So the download happens in the background, without any noticeable delay.

The new index may include pointers to new articles. If a user runs a search that turns up one of those articles, and the user chooses it, the Help Viewer can download that article from the Web.

Whenever the user selects an article, the Help Viewer looks for it among cached files, then looks on the Web, and if there is no Web connection, on the hard disk among the existing help files. “In other words, the old files are used only if newer files are not available.”

If the user happens to be disconnected from the Internet at the time and wants to view a topic that was not included with the product that they haven’t previously viewed, an alert announces that the article is only available via the Internet.

“Having the index local is important. If you are disconnected, you know about the new pages but can’t necessarily get to them. For example, you might get three hits: two local, maybe in cached versions, but maybe a third page that you do not have, and you need an Internet connection to get it. But now you know there is information out there. This lets us push announcements, notifications of new content.”

What about filenames and locations? The index offers an ID for each topic and searches for that ID on files within the help directory on the Web or hard disk—rather than using a filename or a path. “We put that in place so applications could call pages of help from a dialog box. The application might not know what filename to point to. What if a writer rewrote and renamed the file? We would have to revise the application to match. So we use ID references, at first only from dialog boxes, and now within the whole help system. On the HTML page, the ID is tucked inside an anchor tag. The index is just a lookup table with IDs.”

And to emphasize that the information is up to date, the team added a date stamp at the top of each help book so users could say, “Wait, this was updated a few weeks ago.” Meyer says, “It’s our way of saying, ‘This is not the same help system you looked at last week.'” (Updates are generally posted every six weeks, after an extensive review cycle—roughly in sync with each system update.)

Table of contents: goodbye, hello

At first, Help was a search-only system, without a hierarchy visible to the user. “It was topics floating in soup.”

The users coming to the new operating system were fairly experienced early adopters, and testing showed that they were successful in finding what they wanted through search—without any table of contents. “If you know what you want to find, and if you can express that in a few words, you get your content more quickly. So we abandoned the table of contents for a couple of releases when the operating system was new. But now that it has matured, we have more content, and we have been able to recast it and rethink it. We know we have been serving people who had specific questions. Now we want to serve people who are just browsing, without a clear conception of what they are looking for. So we have added more table-of-contents-like things to accommodate the person who is just browsing, saying, ‘I don’t know what I want, I just want to poke around.'”

But behind the scenes, the help is still built around search. For instance, each topic ends with a section called Tell Me More, but instead of hard links to particular files, the button launches a predefined search—using the latest content.

From feedback to revision

“We update every six weeks or so. Technically, we could update every day or every hour, but realistically, you have to have some time for reviews. The first few updates after our initial release were 50/50 additions and changes. But over time, we have been doing fewer new topics and more corrections. As the product matures, we can do more troubleshooting, particularly in response to feedback gathered by our support teams.”

And because the Help team delivers new and revised content via the Web, they can get some idea of what people are asking questions about, just by watching the access log for the most “popular” topics.

“But tracking downloads is only one data point. It is hard to translate that one point into action. So we correlate that information with support calls and accesses to the support database online, and we get feedback from marketing. Also, built into all products is an opportunity to send feedback to Apple, where users can write free form. The writer has to look at all this feedback.”

Each writer, then, is responsible for a topic area, reading through the feedback and writing updates, corrections, and enhancements.


This continuous publishing model means that “Writers are not done and free to move on to something else. You are constantly tending your garden.” But the process is well considered. “Each change is proposed, made, and reviewed before posting.”

When this new system was put in place by Meyer’s small group (five, growing to eight), other help teams were still using Go Live, creating HTML pages by hand and, inevitably, churning out inconsistencies (Why are these dots blue?)—nonstandard formats that had to be corrected in a tedious production process. The new approach meant that writers never did any formatting, so “When it went to production, it flew right through, and we ended up with more time to work on the content.”

Other managers noticed. “They said, ‘We want to use it, too. When can we start?'” Many groups quickly adopted this model.

They were abandoning the idea that a writer should create a series of documents—files, help pages, or Web pages. Instead, writers filled out forms in a database, and software did all the formatting, including dividing the raw material up into distinct Web pages. The help teams all began to move toward one topic per page, a search-based help system, and continuously updated documentation via the Web.

Using a database was incidental but convenient. The team never had a full-time engineer or a content management system dedicated to this effort. Writers and production people put together this new system without a lot of money, relying on off-the-shelf software, with a little tweaking. You could, too.

But according to Meyer, the key is the work you do before the transition—doing your content homework. For instance, Meyer’s team started out by putting search at the heart of the help and, building around that idea, they simplified page design and chose to do only one topic per page. Now they had a soup of individual topics.

“That’s when the ah-ha moment came, and we realized, we can author this in a completely new way.” Using a database to enter content enforced a standard structure in every topic and separated content from format, which was applied automatically after the XML export. Because this process prevented individual authors from getting creative with the formatting, production went much more quickly than ever before—drawing the attention of other managers and persuading them to adopt a similar approach.

The simplicity of the solution makes it doable in any situation where you believe most of your users will be connected to the Web (or an Intranet) most of the time. The customer gets up-to-date information, and support calls decline. The writers have to adapt to creating content in forms rather than on pages, but they get the benefit of a lot of feedback from the users when they go about updating the material. And instead of writing a book and forgetting it, each writer becomes a real expert in an area; the plus is that they can keep improving the help, but the minus is that they do not have any tangible product to point to, and managers cannot simply say, “Well, you managed to meet your delivery, so you get a merit raise.” For managers, this new approach means coming up with a new way to evaluate writers, taking into account real feedback from customers. And, because writers no longer do formatting, time-to-customer has gone up—speeding up the feedback cycle.

Side bar: Typical components

Most help pages for the Macintosh OSX have a small set of components:


Introductory paragraph: Setting context for the task, discussing any prerequisites or requirements.

Step introduction (optional): Used only if the actual steps do not seem to flow naturally from the title of the page. For instance, if you are troubleshooting and the task is “I can’t eject a CD,” the problem may be that the user has file sharing turned on, so we are going to have to tell them how to turn off file sharing, which does not seem, at first glance, relevant to the problem.

Task box: If the procedure is simple, the whole thing may appear in a single paragraph. If there are a few short steps, the team may do away with numbering. (Over five steps, and the numbering comes on). And explanations? “In general, we banned any kind of narrative about how the computer reacts, unless necessary for troubleshooting.” The team also dropped most screenshots, because even fairly sophisticated users were clicking the graphic, as if it were the real interface—and localizing the shots for 21 languages had become a headache.

Outro: The wrap up, suggesting any alternatives. “We just stop. If we are done, we are done.”

Tell me more: A link launching a search for a predefined set of terms in the current content.