Documentation response, part 3

[Rick Mascitti <acad!blitzen!rick>]

>  From xanadu!marcs Mon Mar  5 15:10:46 1990
>  From: xanadu!marcs (Marc Stiegler)
>  To: kmarvin@xxxxxxxx, xanadu!us
>  Subject: Elements of Hyperstyle, Chapter ???: Technical Hyperwriting
>  
>  
>  
>  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, 

Boring for any technical documentation.  Recommended style for novels.

>     2) browse through it, and 

Highly recommended for parts of technical documentation and anthologies.
Reasonable style for non-fiction works, particularly textbooks.

>     3) track through it. 
>  

Required style for using tools to implement software.  "I want to
use flubnuts, I know from reading the TOC and overview that this
system supports flubnuts, now what are the syntax and semantics of
the flubnuts module?"

There is also reading method

      4) skim through it.

I find this useful for first-order reading of technical documents.
It gives me a sketchy overview and a rough roadmap of (usually hardcopy)
documents.  The online version of this may be considered "flash reading"
where one calls up the next page as soon as the current one has made
some (small) amount of registration on the optical path.  (You might
be surprised how much the human brain can retain without actually
"reading."  This is the basic tenet of the Evelyn Wood speedreading
method and improves with training and practice.)

>  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. 
>  

Permuted indices are highly desirable.

>  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.
>  

Hmmm.  Reading as a degenerate case of browsing?  Maybe. or not.

>  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,

My intuition tells me that this is not a good cognitive organization.

>                                          with a map at every branching 
>  point.

With the "narrow and deep" organization, these would be very necessary.
They're an excellent orienting idea, anyway.

>         There are no cycles anywhere in Hypercard Help. There 
>  is little subtree sharing.

I think this is more of a reflection of the difficulties of Hypercard
than a cognitive design objective.  Cycles and sharing can be powerful
organizing structures.

>                             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.
>  

This is all true.  It is not necessarily wonderful.  Although you get
a good local orientation, you might end up doing a lot of back-up, back-down
another branch moving due to loss of global orientation.

Another Hypercard problem is singletasking.  Sometimes I'd like to be
working multiple browse paths at once.

>  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. 
>  

Browsing is best for overview purposes, arguably best for interactive
development environments like Hypercard (and Montage), and *not*
best for looking up the specific syntax and semantics of a support
module.

>  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. 

I think you're comparing apples and excrement.  Browsing would be
better for Word (as it would help provide a conceptual framework
[if one exists for Word :-)] in which to use the application qua
application).  Browsing mode helps best in *exploring* the capabilities
of Hypercard, but isn't nearly so good for finding the description
of repeat while/with/until/for.

>  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.
>  

Does this hold true when your users are experienced system builders?
This is the audience I expect for a C/C++ toolkit.  Your arguments
are certainly appropriate for the expected audience for a Montage-like
product, but I'm not so sure when we're talking about Real Programmers (tm).

>  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).
>  

Again I ask if there should be a distinction between a touchy-feely
interactive development environment for relative novices versus a
hacker support library.  But then, in answer to my own question, I'd
point out that the browsing mode *is* important for Montage, we're
gonna do it anyway, and the concepts are the same for any supported
environment.  So, what the heck, why not have it intrinsic to the
documentation for all the environments?

>  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.
>  

I agree.  Sometimes it's so cute it's cloying.  I prefer a slightly
more dignified approach.

>  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!
>  

Is this a function of user training or good organization?  Both?
I can type real fast on a qwerty keyboard, you can use a chord.
I can tinkle on a piano, McCoy Tyner can work wonders with one.
I can hit a golf ball as far as a pro much taller than I.  What
does this have to do with the price of butter in Russia?  I think
that once some fundamental cognitive rules are met (7 +/- 2,
location of frequent picks, chunking, etc.), the rest is user training.

>  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

Ok.  So far I disagree with some of your supporting arguments but I'm
buying the whole package.  Let's continue.

rick