Format of manual

[Daniel L. Weinreb <DLW@SCRC-QUABBIN>]

I agree with Scott's message.  I've spent many hours working on Lisp
documentation (the Lisp Machine Manual), and there's one point I'd like
to respond to: descriptions of individual functions are the easiest
thing to write.  While the existing CLtL isn't sufficiently specific in
its descriptions of some functions, this is not its primary problem.

The real hard part in writing such documentation is explaining the
concepts.  This is particularly hard when you're writing a standards
document, that needs to be very precise.  While I agree that the
stylized form of function documentation that JKF suggested, and that the
Lucid documentation uses, is a good thing, it should not be viewed as
the most important change towards producing a clear and specific manual.

In my experience, there is an important tradeoff between writing a
manual useful for a reader who's learning what the manual says, and
writing a manual that's very clear and specific.  It's hardly impossible
to do some of each, but it's very hard, because often one goal gets in
the way of the other.

I'd recommend that the guideline for the new CL spec is that it should
attempt to present the material in a logical, ordered fashion that
builds from the bottom to the top, and it should attempt to assume that
the reader is not yet familiar with concepts not yet presented, but it
should above all be strict and precise, even if this conflicts with the
other goals.

The balance is subtle and hard to measure precisely.  I agree with Scott
that we'll have to experiment some to find the right tradeoff.  I also
agree that starting with the existing material, and modifying it to be
closer to what we want, is more likely to succeed than an attempt to
start from scratch.