manual organization

[brlewis at alum dot mit dot edu]

Per Bothner <per@bothner.com> writes:

> The manual has concentrated on being a reference manual.
> It does need some more tutorial or "cook-book" info.
> The question is whether to mingle the tutorial and reference
> information, and have them in separate parts of the manual.

Here's my rationale for separate sections: Most users who want a
tutorial are interested in quickly learning the standard things the
tool is used for.  Precise reference material only gets in the way.
Those users who want to learn the more subtle nuances of a particular
procedure or syntax can just flip to the index and find the reference.

Another advantage of separate sections is that one person can write
the reference section and another write the tutorial section.

Particularly confusing items in the reference section might cross-ref
the tutorial section, e.g. primitive-[whichever]-method.

--
Bruce R. Lewis