Creating Online Help with Tinderbox
by Matt Neuburg03/30/2004
When developer Mark Alldritt and I sat down to plan the documentation for Affrus, Late Night Software's new Perl editor and debugger, I made the following suggestion: "Let's not provide a 'narrative' document; let's use online help instead."
This article explains that suggestion, and describes how we ultimately constructed Affrus's online help using a note-taking hypertext outliner called Tinderbox.
Pitfalls of Narrative Help
A "narrative" help document, such as Mark and I had provided for Version 3 of Late Night's Script Debugger, is essentially an ebook –- a single document of some length, with numbered pages, divided into chapters and sections, presented to the user as a PDF file.
I liked the Script Debugger documentation, but the narrative format had turned out to have some disadvantages:
|
Related Reading 
|
- Many users were not even noticing that the documentation existed, and those who did were sometimes not fully benefiting from it. For example, we received complaints that there was no "reference" chapter; there was, but some users had evidently tired of reading before discovering it.
- A narrative document is bulky, because much of it consists of "glue" or "signpost" paragraphs to clarify to the reader the document's structure and train of thought. This bulk, or fluff, is painful to write and tedious to read.
- Even a good narrative document is not every user's cup of tea. Often a user just wants to look up some single fact. Even with an index, a table of contents, bookmarks, links, and all the other paraphernalia of which a PDF is capable, it's often difficult to find something in a narrative document.
- A narrative document is hard for the author to maintain. We were going to begin the documentation as the software itself was still in an early alpha state, and I didn't relish the prospect of having to reread the whole of my draft everyday, to see what that day's new build had falsified in the documentation and fix it.
Yes, Virginia, There Is Good Online Help
When I suggested using online help, Mark was skeptical; and this was not surprising. By "online help" I meant help done the official way -- Apple's way, also known as Apple Help. Apple Help has a bad reputation. In Mac OS 9, Apple Guide was a clunky mess; in the early years of Mac OS X, Help Viewer could take more than a minute just to launch. Users resented having to use Apple Help, and developers were correspondingly reluctant to include it.
But Panther's Help Viewer is free of the slow-launch problem; and, looking at the facts in the clear light of day, one sees that Apple Help actually offers several advantages:
- Behind the scenes, a Help Book is merely a bunch of web pages. There are many tools for creating web pages, and Panther's Help Viewer uses the Web Kit to display them, so it displays them well.
- Apple Help provides searchability for free; this too is much improved in Panther.
- Specific interface items in the application can be tied to particular pages in the Help Book, so that a Help contextual menu item or button jumps directly to the appropriate discussion.
Much of Apple Help's bad reputation these days is actually due, not to any systemic flaw, but to bad content. Writing clear, helpful web pages is not easy! In arguing for the Apple Help approach, I envisioned following certain guidelines that would make life easier for both author and reader:
- Pages should be short, without unnecessary "glue" verbiage. If possible, the reader should not have to scroll in order to see the whole of a page.
- The entire Help Book should have a hierarchical structure. In essence, it should be an outline: topics within topics within topics, where, at any level, a topic and its siblings are ordered.
- Navigation should be excellent. "Breadcrumbs" should show the trail of links down from the top level to the current page. Previous and Next links should show the adjacent sibling topics at this level, an Up link should show the containing topic, and Further Details links should show any deeper topics contained in this one. (I see far too many online help books where pages have no navigation at all; the user is forced to use the Back button after reading every page. That, in my view, is an infuriating and atrocious practice.)
- Quite aside from navigation, there should be extensive use of links between pages. A word or phrase used on one page but explained or further discussed on another should be marked by a link, so that the reader can go directly to the explanation.
- Conversely, the pages should evince a certain willingness to repeat content; i.e., where possible, the same content should appear on multiple pages, rather than making the reader click a link. This is to minimize YAWP (Yet Another Web Page), the phenomenon where the reader winds up annoyed at having to click the mouse too many times.
- Illustrations (screenshots) should be used, though this should not be overdone, since the reader is presumably looking right at Affrus' interface already. In general it is pointless to repeat in the Help what is evident to the reader by a direct inspection of the application.
Here's how some of these strictures ultimately manifested themselves in the layout of the Help pages:
Above, you can see one sort of very typical page. The page is mostly navigational in nature; it has some perfunctory content, and that content includes plenty of links. But mostly this page serves simply as a major heading. At the top are the "breadcrumbs"; at the bottom are the Further Details (downward) links and the Up, Previous, and Next links.
Now let's click the first Further Details link:
That is the other sort of typical page, containing actual explanation. The explanation is self-contained and confined to a single topic, it is direct and devoid of fluff, it is short enough to fit in the window without scrolling, and it relies heavily on links to other topics.
Pages: 1, 2 |
