Documentation, chunkiness, paper, screens, and fun

[John Walker <acad!throop!kelvin>]

Here are some off-the-wall comments that have been stirring around
in my skull during the recent discussion of Xanadu on-line documentation
and documentation styles in general.

First, it seems to me that one of the things that wonderfully done
paper documentation does _really well_ and most on-line documentation
does terribly is accommodating a a diverse set of readers with different
styles of reading and differing intent in using the document.  Supplemented
by a good table of contents and index and supported by consistent
typographical conventions and design elements (such as sidebars and
boxes, where appropriate), a paper document can be read straight
through on different levels, browsed, or used for quick lookup of
specific information.  The bad news is that developing these tools
to support the reader often takes as long, and is just as difficult as writing
the text in the first place (which is why they're so often absent or
awful).  The only way to make a good index is with 3x5 cards, a pencil
with a big eraser, and lots and lots of time for shuffling categories
and redoing earlier work when they shift.

Note also that a single reader may use the same document in very
different modes at different points in time: for example, reading it
straight through initially, then using it as a reference or, conversely,
raiding it for nuggets of information needed immediately, then returning
to browse or read it at leisure at a later date.

One of the things that makes so much on-line documentation awful is that
it tends to impose the designer's style of reading on the user, not
allowing the user to choose what's best for him at the moment, as he
can with paper.  When ze computer decides ven you can flip ze pages, and
where to, it has deprived you of a fundamental freedom and means of
access that's inuitive to that minority who can read.  "Your papers are
not in order...."

Clearly, it doesn't have to be that way.  Xanadu provides the freedom to
do anything we want, and one hopes this freedom will be used to produce
something better than paper (which is, after all, why we're doing this,
right?).  But the power of Xanadu doesn't prevent us from creating
inflexible and impenetrable structures that confine the user into one style
of reading.

I think that Marc Stiegler's observation that screen resolution is one of
the factors contributing to bad on-line documentation is right on.  OK,
I'll say it.  I don't like Hypercard, and here's why: I can't ever see
enough at one time, and every time I go somewhere, the little bit I could
see through that tiny little hole goes away and is replaced by another
little nibbet of information.  Yes, the history makes navigation
much better than anything else I've seen, and consistent use of navigation
buttons by the stack designer really helps, but Dammit, it's like
saying you have the most comfortable cinder block to bash your head
with instead of suggesting you stop bashing your head entirely.  I don't
_want_ to shuffle a lot of little screens: if the data are presented best
in chunks of screen size, then at least let me get 20 or 30 of them on
my tube at the same time so I can refer back and forth without all this
infernal flipping.  (My original Xanadu 88.1 Sun front-end embodied
this bias of mine, and I really liked how it felt to use it.  Others,
of course, will probably hate it.  They will use a different front-end.)

Paper works surprisingly well in this mode.  Manuals I'm actively using
frequently have several bookmarks in them, and I use those little
plastic removable tabs you can write on for semi-permanent indexes
to frequently-accessed information.  For C function calls, for
example, I have all the manual pages on-line and CATMANed for instant
access, but most times I pick up the Turbo C manual (which contains
essentially the same information) because I can find what I need
faster that way.  Designing around a little tiny peephole of a computer
screen has imposed limitations on computer-mediated documentation
that are compromises rather than improvements, but which many users
mistake as inherent properties of on-line documentation.  (Just as
not that many years ago EVERYBODY KNEW THAT COMPUTERS ALWAYS SPOKE IN
CAPITAL LETTERS.)

Whether what we make is fun or not, it must not be frustrating.  If
we can't use Xanadu to make documentation that's better that a printed
manual, how do we expect others to believe we've developed something
that will supplant books?