Path: utzoo!attcan!uunet!husc6!mailrus!cornell!uw-beaver!tektronix!tekcrl!NTP server version 1.5 (26 Feb 88) ready at Sun Aug  7 1!willc
From: willc@tekcrl.TEK.COM (Will Clinger)
Newsgroups: comp.lang.lisp
Subject: exposing the implementation (was Re: Another Lucid Question)
Summary: is a bad idea
Message-ID: <2912@tekcrl.CRL.TEK.COM>
Date: 7 Aug 88 21:11:56 GMT
References: <3384@phoenix.Princeton.EDU> <6882@bcsaic.UUCP> <3424@phoenix.Princeton.EDU>
Sender: ftp@tekcrl.CRL.TEK.COM
Reply-To: willc@tekchips.CRL.TEK.COM (Will Clinger)
Distribution: na
Organization: Tektronix, Inc., Beaverton,  OR.
Lines: 30

In article <3424@phoenix.Princeton.EDU> eliot@phoenix.Princeton.EDU (Eliot Handelman) writes:
>I just want to make a practical suggestion to lisp documenters: I think
>it makes sense to indicate the existence of EVERYTHING available in the lisp,
>in EVERY package, regardless whether or not it's felt that the user has
>the right to use these things are not. And considering the volume and expense
>of the Lucid doc, I can't see why this was not done. Counterarguments?

People who use procedures and variables that are intended to be private to
an implementation might get a little upset if the feature they rely upon
in Lisp version 7.14 disappears in version 7.15.  The documentation could
say of such features that they should not be relied upon and that anyone
who uses them is crazy, but some people would still interpret the fact
that they are documented at all as an implied warranty of stability.  Any
system that documented such features would be inviting the wrath of its
users.

It also costs a lot of money to generate pretty, polished documentation
that can be distributed to users.  For system internals, that money would
be better spent on ugly, rough, but more complete internal documentation.
The customer would ultimately benefit from greater reliability and more
timely enhancements.

All things considered, it seems to me that users are much better off when
they don't know anything about ephemeral system internals.  The fact that
they can easily learn about undocumented system quirks by browsing the
package system is just one more sign that the package system is not a
satisfactory solution for programming-in-the-large.

William Clinger
Semantic Microsystems, Inc.