Path: utzoo!mnetor!uunet!husc6!cmcl2!nrl-cmf!ames!pasteur!ucbvax!THINK.COM!gls
From: gls@THINK.COM
Newsgroups: comp.lang.scheme
Subject: Extending the address space of MIT Cscheme (semi-long reply)
Message-ID: <8805051450.AA03093@kali.think.com>
Date: 5 May 88 14:50:16 GMT
References: <8805040747.AA21368@kleph>
Sender: daemon@ucbvax.BERKELEY.EDU
Organization: The Internet
Lines: 40


   Date: Wed, 4 May 88 03:47:10 edt
   From: cph@kleph.ai.mit.edu (Chris Hanson)
   Reply-To: cph@zurich.ai.mit.edu

   * We have virtually no documentation.  This is obviously a terrible
   thing, and we are in fact generating some.  But the bottom line for
   this is simply lack of time, plus the fact that none of us has much
   text writing experience.

I have not seen the code for CScheme, and did not particularly want to jump
into the middle of this flame, but I have a set of points to make about
documentation in general, as one who has written a lot of a code for
publication and also a lot of text.

(1) The way you get experience at writing text is to write text.  (When you
first started programming you didn't have much experience at programming,
either, but you obviously didn't let *that* stop you.)

(2) Lack of documentation often stems from the belief that the code is so
clear to you (because you've got it all in your head) that you'll have no
trouble remembering what's going on six months from now.  This belief is
invariably false.  Even if you don't want to write documentation for other
people, write it for the you of six months from now, becase by then you'll
be a different person too.

(3) Writing documentation usually *saves* time in the programming process,
because it takes less time to review design decisions and rediscover how
little details work.

(4) The writing of documentation actually *improves* the code.  The reason
is that it is usually easier to clean up a crock than to have to explain
it.  I have seen this phenomenon hundreds of times in programs of all kinds.

I'm not saying that everyone should write documentation the way Knuth
did for TeX.  I am saying that documentation has a direct intrinsic value to
the programming process, and that lack of experience in no excuse.

--Best regards,
  Guy