Consistency

[Daniel L. Weinreb <DLW@ALDERAAN.SCRC.Symbolics.COM>]

    Date: 19 Feb 87  1752 PST
    From: Dick Gabriel <RPG@SAIL.STANFORD.EDU>

    At this point I'm worried about a couple of new things: first, that
    the Common-Lisp-skeptics will accuse us of doing to object-oriented
    programming what we did to Lisp: obfuscate and ruin it; second, that
    the proposal might be in jeopardy because it is too complex. 

I share your worries about this.

However, it's not too surprising, since all we're giving the community
is a reference manual.  Reference manuals are good for DEFINING a
standard, but they aren't so good for SELLING a standard.

(For example, I am absolutely convinced that Scott Fahlman's snarling
antipathy to Flavors is due entirely to the fact that the Flavors
documentation that Moon and I wrote doesn't separate the easy,
everyday features from the sophisticated, only-for-experts features,
thus giving a false impression that you must master great complexity
in order to do even the simplest thing.)

Based on all my experience with technical writing, I don't think it's
practical or desirable to try to come up with a single document that
serves both as a precise reference for CLOS, and also as a friendly
introduction to CLOS.

    I still believe that we are writing a specification, and it would be wrong
    to put fluffy, imprecise language into the document...

    When I decide to write things using mathematical notation, for example, it
    is because I cannot think of how to unambiguously express the concepts in
    English....

Exactly.  The problem is that what you call "fluffy, imprecise
English" is often the best way to TEACH someone about something.  You
use conversational English to establish the basic idea, the
motivation, the paradigm; then you use precise, rigorous, and maybe
even mathematical language to explain it in such a way that the user
can be sure of understanding all the cases, including complicated
interations, and so on.  Papers like the ones mailed out as
X3J13/86-018, or something even gentler, are more like what you'd want
for teaching the basic concepts.

I don't know whether something like this could be produced in time for
distribution at the next X3J13 meeting.  At least, though, when we
present the material, we can take that kind of gentle approach, and
remind people several times that what they're holding is a reference
manual, not a tutorial, and not to think that everybody would learn
CLOS by reading the reference manual.