Re: documentation... more

[Michael McClary <michael>]

> From marcs Mon Mar 12 14:54:27 1990
> 
> Rick's discussion of top-down-ness and bottom-up-ness bring up 
> another interesting possibility with Xanadu: the ability to have 
> it both ways. We could build 2 documents that cover the same 
> material, one bottom up and one top down, using vcopies and resequencing 
> in the inclusion list, and probably some version-specific material. 
> [You could hop from one mode to another by following a link.]

I had been assuming that was the way we'd be doing it:  Multiple
documents constructed from the same text but in different formats
by vcopy, tied with links.  (Links might have two ends on the same
text, but in different contexts...)  Perhaps I should have spoken up?

> This might be useful, or it might be a nightmare--my head hurts 
> when I think about writing it, and such a weaving would involve 
> more cycles than you could shake a stick at. But it could be 
> interesting to experiment with.

My impression is that any given text will work best for one of the forms,
but leave the others looking patchy.  I'd expect the best results if one
were to write the text initially for the little-chunk case, then vcopy each
into the big sequential manual (as chapter- or section- introductions/
outlines) and edit it to flesh it out into the other format, as one would
write a chapter from an outline.  This might end up fragmenting the material
at the link end, but that's not a problem, at least for the implementation.

Of course, one would work back-and-forth between the forms, vcopying
particularly sweet prose to other forms when it fits them well.

> [semi-formal experiment, taught 2 sections bottom up, the other 2 sections
> top down.  The groups that learned bottom up averaged higher scores.]

Anecdotal evidence:  I learned programming about as bottom-up as you
could get.  In addition to being able to DO something at any stage,
I constantly found that understanding what was being done "behind the
curtain" (at closer-to-machine levels) aided my understanding of what
I needed to do.

	michael