Elements of Hyperstyle, Chapter ???: Technical Hyperwriting

[Marc Stiegler <marcs>]

This message has four major sections: 

   First there is a comparison of several online documentation 
systems, leading to a conclusion that a key strength in Hypercard 
Help is its multi-modal readability, with a particular strength 
in browsing. 
   Second, we investigate these different human reading modalities, 
with a particular emphasis on how to make a document browsable. 
   Third comes a brief discussion of why browsing is most important 
as well as most difficult to support of the human reading styles. 
   Finally, we look at other striking features of Hypercard Help 
that make it a joy to work with.

Too many attempts at online documentation advertise the half-hearted 
nature of their development. In Microsoft Word, the online help 
is presented as an alphabetically sorted series of topics. The 
page of material on each topic has a "next" command, which takes 
you to the next obvious item on the list: this clever arrangement 
takes you directly from "finding text" to "font sizes".  Needless 
to say, the flow leaves something to be desired. You can track 
things down in Word Help, but you can't really read about them.

The CD-ROM version of Inside Macintosh fails in the other direction. 
This bytesize copy of Inside Macintosh is indeed just a copy 
of Inside Macintosh: they digitized the paper text, dumped each 
chapter into a hypercard, and built an index that will zero you 
right in on the key chapter...well, it will zero you in on the 
chaper, anyway. A chapter in Inside Macintosh is an awful big 
chunk; there's nothing pithy about it. You can read about things, 
but you can't really track them down. 

In contrast to these weak efforts, the Hypercard Tutorial and 
Help system shines. You can investigate Hypercard Help in at 
least three distinctly different ways. You can:

   1) read it linearly, 
   2) browse through it, and 
   3) track through it. 

Linear reading means, of course, there's a "next page" that the 
reader can follow most easily, where the following page continues 
smoothly from the preceding page. Tracking means clicking through 
the indices to find the specific item you're looking for, perhaps 
something you've read about in the past, but don't quite remember 
any more. 

Browsing is a curious blend of the two. When browsing, you want 
to follow threads a little distance, but you want to jump threads 
before getting too immersed, and check out the other threads. 
When browsing, you want frequent opportunities to pause for a 
moment, and consider whether to continue in the forward direction 
or to jump to something else.

Browsing is the subtlest and most poorly understood of the three 
reading modes; the vigor of the browsing mechanism in Hypercard 
Help is what sets it apart from the other online helps. Browsing 
includes elements of both reading and tracking; reading and tracking 
are to some extent degenerate cases of browsing. So let us look 
at the problems of browsing first.

For browsing, you want to make frequent re-evaluations of what 
to read next. Ok, so what do you do to support frequent re-evaluations? 
 There are 2 critical elements for re-evaluation: control of 
information chunk size, and maintenance of numerous local "road 
maps".

Browsable chunks of data are small. With small chunks, the user 
gets to pause often and consider his direction--the crucial element 
of browsing. In Hypercard, making small chunks is so easy it 
is automatic: the card itself represents a small chunk. At the 
end of every card you can choose to go forward, go backward, 
or go back to the most recent map. 

The "most recent map" is the local road map in Hypercard Help. 
If you go and study the architecture of Hypercard's Help, you 
will find, as I did, that the backbone is a surprisingly deep, 
surprisingly narrow, small-leafed tree, with a map at every branching 
point. There are no cycles anywhere in Hypercard Help. There 
is little subtree sharing. Few leaves in this tree have threads 
of more than 3 cards. Few of the branch points (the maps) have 
more than 10 items in the map to choose among. 

Because there are many local maps, when you jump back to a recent 
map, you aren't going very far. Because maps appear frequently, 
you regularly get a modest but significant group of choices beyond 
just the choice of forward, backward, and back to map. The small 
frequent maps minimize the sense of disorientation as you browse: 
small maps mean you understand them at a glance; frequent maps 
mean you still remember them; and short threads mean you don't 
have to go very far to finish. Each step lures you on to the 
next, or on to something else that is somehow related.

Reading is easier to characterize. For simple reading, we can 
look at the structure of conventional literature as a guide. 
 Linear material usually has large leaves (chapters or sections). 
The tree is shallow compared to the browsing tree; the number 
of branches at a branch point remains about 10, perhaps a few 
more.

When tracking, the tree has small leaves, but now the number 
of branches at a branch point may be quite large: the conventional 
book index is the extreme form of this very shallow but very 
wide tree.

Of the three forms of online investigation, the most important 
one is, I believe, browsing. Linear reading is least important. 
People read better with books and paper; that is how they will 
"read" Xanadu information as well, those who elect to approach 
it that way. 

Tracking through the documentation is important, but my comparison 
of Hypercard Help (best for browsing) and Word 4.0 Help (best 
for tracking) suggests that browsing is still more important. 
Good tracking helps the experienced user, but browsing helps 
the beginner. And it's the beginner who needs the most help--and 
it's the beginner who makes your product, or breaks it.

Consequently, when we build our online documentation, we need 
to focus on browsing support, as Hypercard did. We should follow 
this strategy regardless of our audience (at least, regardless 
of our audience as long as an important fraction of the audience 
includes beginners).

Hypercard has two other striking features that the other systems 
lack:

   1) explanation through implementation, and 
   2) graphically memorable mapping.

Explanation through implementation is probably Hypercard's most 
endearing characteristic, the attribute from which Hypercard 
derives most of its "cuteness". Throughout the Help stacks, features 
are presented by using the features themselves in new and novel 
ways. In one place, there's a button which pops open a post-it 
note containing a bit of extra information; in another place, 
there's a button that just takes you on a one-card alternate 
branch for the extra material. Thus, Hypercard Help is often 
a surprise--which is both a strength and a weakness. It's a strength 
because of the gamelike delight it can bring; it's a weakness 
because it's disorienting. The technique works well when the 
Help system is intended to teach you about the Help system's 
system, as in Hypercard; it would be unwise, I believe, when 
attempting to explain other materials, as we will.

The graphically memorable mapping is a surprisingly enduring 
strength. When I use Hypercard, there's a particular section 
of the Help system that I use more than all others combined: 
the list of functions. This list is reached by clicking for Help, 
then clicking for Hypertalk, then clicking for Functions.  Both 
the Hypertalk button and the Functions button are located, not 
in the middle of a long list, but in distinctive locations on 
card maps. Even when months pass between my encounters with Hypercard, 
I can still hit the locations of the Hypertalk and Function button 
without reading the maps--my fingers and eyes have memorized 
the location of the button, independent of labeling and other 
features. Because of this memorable graphical representation, 
I can find items in Hypercard Help through the browsing mechanism 
faster than I can find them through the indexing mechanism!

Having characterized so many features of good online documentation, 
the next question is, of course, can we implement these features 
with our own products? That is the next topic.

--marcs