documentation... more

[Rick Mascitti <acad!blitzen!rick>]

(Appropriately humble...)

I'm very sorry to anyone (especially marcs) who took my
selected tone of response as "cheap shot"ism.  It really
wasn't intended that way.  From now on, I'll temper my
enthusiasm, especially in written form.

ravi, thanks for a great reference.  kelvin, thanks for
better articulating what bothers me about hyperdocumentation.
bobp, good to have you pointing out that the joy of the
tool is more important than its writeup.

While a well-designed tool needs no documentation for 
average use, its nuances do require explanation.  I would
expect Tapestry and Montage to be touchy-feely enough that
exploration will be heavily used to understand their basic
workings.  As marcs points out, toolkits are not in themselves
tools.  But we have a unique opportunity to deliver our
toolkits as living examples of Xanadu hypermedia.  And we
should.  Include a browser and deliver an integrated
package of code (whether source or object), make/build
directions, tests, examples, and links with not only specific
usage directions (manpages) but also more holistic reference
reading.  (This assumes, and I hold rightly so, that all
developers have or have direct access to a back end.)

Regarding chunk vs. stream processing, I think we need to
accomodate both styles.  I think we can without imposing 
a priori size constraints on passages.  There are, indeed,
some existing-world samples from which we can learn.  Not
to belabor the point, but, as an example, consider the
journalist's style:  Headline, lead paragraph, increasingly
detailed paragraphs, sidebars for explicative analysis,
references to editorials and/or releated stories.  A good
journalist organizes the material such that the editor (in
our analogy, the reader) can "chunk" at any paragraph boundary.
Space constraints give this style great survival value.
Our introductory material (the "holistic" stuff referred to
above) should employ this style, linking with all of the
goodies mentioned.  bobp has done a good job of this with
the SysOver.

I'm beginning to see this disagreement as being a top-down (me)
vs. bottom-up (marcs) stylistic debate.  Now I know why the
notion of "inclusion list" was hard for me to grasp. (No cheap
shot intended.)  I envision the authoring process as much like
the newspaper story -- deriving detail from a notion of the
whole.  My impression of marcs' preference is to build ever
more complicated passages from the inclusion of chunky parts
within a planned framework.  Both styles are valid.  Both are
accomodated by Xanadian concepts.  How should our documentation
be developed and presented?  I care only insofar as it doesn't
restrict the reader from any one of a wide variety of reading
styles.  I fear that going in with the attitude that any single
passage has to fit on a Mac Plus or SE screen in 12 (10, 9, who
cares?) point type will make it very hard to ``read'' read
however easy it may be to ``browse'' read.  I'd love to be
wrong since that would mean that we've allowed at least these
two styles.



permuted index:  check out the index in an old Unix(tm) manual.
All the keywords of a function or command description are ways
to track into the description.  Thus (blind example, may be
slightly incorrect) I can get to fseek(3) from any of
fseek, seek, file, stream, pointer (file pointer), and maybe
some others with at most 2 indirections (e.g.:  file ->
seek on file -> fseek).  Frees one from having to browse
a list of function names for likely candidates when one knows
that ``I'm looking for the gizmo that allows random access a file.''
Permuted 'cause (at least in old Unix mans) the description was
rotated around the keyword.



daunted but still discussing,
rick