[Date Prev][Date Next][Thread Prev][Thread Next][Author Index][Date Index][Thread Index]
Tapestries of Online Documentation
- To: <acad!kmarvin>, <us>
- Subject: Tapestries of Online Documentation
- From: Marc Stiegler <marcs>
- Date: Mon, 5 Mar 90 15:52:30 PST
How would we support the features of excellent online documentation
described earlier, using Tapestry or Montage as the presentation
tool? Well, with Montage all bets are off, since you can do anything
with it (at least, you can do anything until we design it in
more detail :-). Tapestry, however, is well defined (too well
defined, some would say :-)
Tapestry was not designed to optimize the presentation of preplanned
hyperdocuments; it was designed to optimize the presentation
of evolving collections of documents. The differences are subtle
For example, in an evolving collection, regions of the pool will
become the targets of dense clusters of links, whereas well designed
preplanned hyperstructures would avoid such complex overlaps.
Because of the focus on evolution, Release 1 of Tapestry is
most concerned with high-density links, using the link pane,
rather than with low-density links, that can be administered
more elegantly with the sparse link sidebar (which is planned
for Release 1.1).
Nevertheless, I think we can make even Release 1 Tapestry-presented
material almost as easy to read, browse, and track through as
Hypercard Help. Paralleling the list of important concepts from
the last message, we will look at:
1) reading techniques, for
a) linear reading,
b) browsing, and
then we will look at
2) explanation through implementation, and
3) graphical mapping, all with Tapestry tools.
For linear reading, simply embody the help system in an inclusion
list: the inclusion list is well designed to incorporate the
sizes of the leafs, and the depth of the tree, needed for linear
For browsing, we need to be able to break the component documents
of the inclusion list into smaller chunks, and we need local
maps. The browser-size chunking may seem like a difficult problem.
Tapestry was designed to be a smooth scrolling system--it was
explicitly intended to break the card barrier imposed by Hypercard.
Consequently, one might think that Hypercard chunkiness would
be very hard to achieve. Surprisingly (even to me :-), there
is a convenient mechanism available:
We can get cardlike chunking by using "bookmarks". A bookmark
in Tapestry is a one-ended link whose descriptor describes the
text phrase to which it is attached (we would probably make these
bookmarks of the link type "bookmark"). People with keen memories
and an eye for detail will remember from the Capabilities Review
that, when you click on a link in the link pane, the text pane
jumps to the closest chunk of material in the LinkEnd, and highlights
the LinkEnd. Thus, by clicking on one bookmark after the next
in the link pane, the reader can jump from chunk to chunk sequentially.
It is not clear to me whether the linear-reader's inclusion list
should treat every separate browsable chunk as a separate document.
My first reaction is that it should not: it would be too broken
up to be a good basis for reading.
For the local maps, introduce each major topic by creating what
I refer to as a "road map" when I am critiquing other people's
documents: introduce the major topic by briefly describing all
the subtopics, and explaining why you're going to cover those
subtopics in that order. Then draw a link, from the phrase describing
each subtopic, to the subtopic itself. Since the link is bidirectional,
lo!--you also have the link to get back to the local map. The
map is itself a chunk, of course, with a bookmark linked to it
so you can select the map itself as the item of interest.
We can also build an intriguing map of maps in Tapestry: create
a noncontiguous link that has, as its linkEnd, all the local
maps. When you select this link, you highlight all the maps,
and you can browse the maps by clicking the "go to next highlighted
area" arrow on the Tapestry scroll bar. I think this will be
not only cute, but also useful.
So much for browsing. Finally, for tracking, create an inclusion
list for which each headline is an index entry that has a link
to the chunk or chunks that explain it. If each chunk is a separate
document, the chunks can themselves be the body of this inclusion
list; assuming the chunks are not separate documents, the index
inclusion list would be "empty", i.e., it would have no documents
behind the headlines.
Between these techniques, we have covered all the major modes
Next, how do we embody explanation through implementation? Or
should we? As noted earlier, explanation through implementation
is not generally effective when used to teach systems other than
the system behind the documentation itself (as Hypercard Help
uses Hypercard features to explain Hypercard). However, we have
an opportunity for a modest cousin of this when we build third
party documentation in Tapestry. It depends on using fine grain
links, for which there is no equivalent in Hypercard:
Basically, we can use bookmarks not only for chunking, but also
to extract code templates from examples. For example, let us
look at a part of the HyperHelp definition for the If statement:
If <expression> then
By attaching a bookmark to a noncontinguous piece of the example
itself, we could allow the user to click once, Copy, and Paste
into his own source code the following:
If x then
In this way, the template and the example are the same material;
which one you get depends on which bookmark you click. Also,
if the developer is maintaining his source in Xanadu, when he
pastes the template into his source, there is a direct link back
to the part of the manual that describes it.
To get visual cuing on the road maps, use columns for the components
of the road map whenever possible, and using visual blocking
for each cluster of 4-6 entries in the map. We can use graphics,
simple dashes, or group titles, for each cluster.
That's all the ideas I have at the moment. Even though Tapestry
is not optimal for developing online documentation, I think it
will work well for us. Interestingly, I predict that, for our
customers who want to write Help for THEIR customers, I believe
that Tapestry may work BETTER than Hypercard.
How can I make such an outrageous statement? Simply by noting
how few people other than the Hypercard people themselves have
successfully used the power of Hypercard to present their documentation.
For documentation, Hypercard is a dangerously low-level tool.
It is possible to custom craft your stack to a wonderful extent.
But there is no choice about it: you MUST custom craft. Hypercard
supplies plenty of tools, but few documentation-oriented libraries
or defaults. It is very expensive to build a good Hypercard-based
Tapestry, however, supplies defaults that are easy to use. Where
Hypercard still needs someone with some level of programming
skill, and an artistic eye, to get anywhere with it, Tapestry
will not. If Tapestry works at all, it will be completely accessible
to anybody who can edit and link.
And of course, Tapestry users will have something extra to help
them: an online style guide, with discussions like this one :-)
P.S. Some of you may have noticed that this multi-message treatise
has a large number of local maps and small chunks, even though
it is also organized with a shallow tree with large leafs and
linear transitions. You might wonder whether the entire series
is an experiment in hypermedia style, intended to be hypermedia-ready
copy that we can load into Tapestry, link, and assess as online
The answer is yes :-)