Tapestries of Online Documentation

[Marc Stiegler <marcs>]

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

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 
       c) tracking, 
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 
reading.

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

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
      <command>
      <command>
   end if

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

   end if

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

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

The answer is yes :-)

--marcs