Documentation riposte, part 4

[Rick Mascitti <acad!blitzen!rick>]

Ok, ok.  No more for a while.  Remember, I didn't choose
the passage size.

>  From xanadu!marcs Mon Mar  5 16:12:48 1990
>  From: xanadu!marcs (Marc Stiegler)
>  To: kmarvin@xxxxxxxx, xanadu!us
>  Subject: Tapestries of Online Documentation
>  
>  
>  
>  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 :-)
>  

Now, now, Marc.  Glass houses and all that.  I doubt very much that
Montage would make a good bedmate, brew coffee, or even vacuum the carpet.
I hope that after you see the design-so-far that you'll have a better
feel for the browsing and editing capabilities.

>  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 this application, the differences are *very* important.  I see
more of a bulk-pour-text-then-add-links (I guess this describes
"preplanned hyperdocuments", no?) process than one of group decision-
making or evolutionary discussion.  Tapestry is excellent for the latter,
but I doubt it's the best vehicle for the former.  It's not clear that
we're actually developing such a tool, either (mistake??) -- the
Montage brower/editors combo might work better but here the emphasis
is on interactivity with respect to application development, not
data-entry-intensive types of work.

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

Duh?  The passages are written in a "natural size" and are included
via inclusion lists in some logical ordering.  Why in heaven's name
would you want to subdivide a passage written in optimal size?  What
does the original passage size have to do with the exchange rate of
the zloty when you can link to arbitrary-sized sections?  I'm real
confused by this requirement.

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

Double-duh?  Why are we inventing yet another artificial abstraction?
See immediately below.

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

Similarly, the links associated with the visible portion of the passage are
immediately available in the link pane.  As I'm cruising along I can
either be in "reading" mode or in "browsing" mode. This is *my* choice as
reader, not *yours* as writer, kemosabe!  This is what is so *bogus* about
everything in Hypercard, I don't *ever* have the choice to be a linear
reader, so nobody ever writes anything worth reading linearly.  To shift
into "browse" mode, I inspect the link pane, see an interesting LinkType,
select it, and off I go....

I completely fail to understand why you are artificially chunking passages.

>               Thus, by clicking on one bookmark after the next 
>  in the link pane, the reader can jump from chunk to chunk sequentially.
>  

Yuck!

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

Again, why are we breaking it up so?

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

Lose this chunky bookmark idea before I get sick all over my keyboard.
(Sorry for the increasing vehemence, but such is the nature of responding
in batch mode.  I want a Tapestry, *now*, so we can discuss this properly.)

I'm not sure I understand the map idea.  Let me try rephrasing...

Since the documentation is (as delivered) a static entity, we can embed
maps at strategic places and link to them.  Like any other document
we can link to (hence, through) them to other material.  Nondirectionality
allows us to traverse "down" ("forward") or "up" ("back") with ease.

What about users' adding to our as-supplied documentation?  Is it
their responsibility to update the maps?  Some time ago we discussed
dynamic mapping of hyperpaths.  I want to investigate this for the
Montage Browser although I haven't given it much thought.  Such
dynamic mapping should automatically generate/update these local
maps as well as being able to produce a global map (or one at any
level of granularity desired).

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

The global map?

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

Yup.  Straightahead indices are easy.  I will still argue for permuted
indices as well.  See above comments about chunks.

>  Between these techniques, we have covered all the major modes 
>  of reading. 
>  

Yeah, but you've made linear reading so much of a drag as to be avoided.
Lose the chunks, dude, and it becomes doable again.

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

Without bookmarks (So'Philly accent *on*):  I got dis ding in da
overview 'bout LinkEndSets dats gotta link ta da manpage dat shows
da visible parts o'da C++ class dats gotta link ta da test code and
da examples.  (accent *off*)

Isn't this just hypertext?  What am I missing?

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

Yeah.  I think I said this in response letter #2.  We agree.  Good.

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

Chunksizes want to be 5-9 entries. (7 +/- 2) As for the rest, I think
I need a picture.

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

Maybe, but Montage will work better than Tapestry.  Nyah, nyah!

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

The result of small chunks, maybe?

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

Gawd!  I hope that we're not intending to publish such moronic drivel!
Double-smiley :-) :-) back at ya'!

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

You don't have enough local maps.  The passages are too long.
The chunks are too small and disjointed.  You'd have done better with
more natural sized passages and avoided internal chunking.  (I sure
can pick a scab 'till it bleeds, no?)

Good experiment.  I judge it successful for an ongoing discussion but
I'd hate to have to read technical documentation this way.  (Even if I
squint real hard and imagine a Hypermedia browser!)

Whew!
rick