Thanks Tim.  I think the heat here is because if my comments are taken 
personally it looks
like I am calling volunteers lazy.  That is not the case.  Someone is lazy 
when they are
not willing to do what they are responsible for (i.e. what they are paid to 
do or what
the life/happiness of people they are responsible for depend on them to do). 
  If someone
doesn't want to document code that they wrote and gave away for free, that 
doesn't
make them lazy or negative in any way.

But the documentation needs to get done.  So if the author doesn't want to 
thats ok, it's not
bad.  But we can start a documentation project, get people who do want to do 
it and
get this done.  But the worst thing is when people trying to do this project 
don't get the
help they need because everyone thinks it isn't necassary because "the code 
documents
itself".


>From: tim Rowledge <tim at rowledge.org>
>Reply-To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>Subject: Re: Thoughts from an outsider
>Date: Wed, 30 Aug 2006 15:38:40 -0700
>
>
>On 30-Aug-06, at 1:34 PM, Ramon Leon wrote:
>
>>>Communities that tell their users to RTFM find themselves
>>>alone very quickly. We're telling ours to RTFSC. There has
>>>got to be a compromise better than that.
>>>
>>>--Benjamin
>>
>>I never said documentation was bad, I was simply responding to the  
>>invalid
>>accusation that the Smalltalk style of self documenting code is  wrong, or
>>that we're copping out or lying made by JJ below...
>>
>>>And dont go down the road that "smalltalk is simple so the
>>>code documents itself".  The code NEVER documents itself,
>>>that is a cop-out and a bold face lie.
>
>Well I have bit of experience in Smalltalk and I find myself  substantially 
>in agreement with JJ here. Sure, senders and  implementors are fabulous 
>tools to have but they offer nothing to  help understand what is likely to 
>happen with exceptions and very  little for Tweak signals etc. No amount of 
>staring at source code  will tell you what the author might have *wanted* 
>the code to do, nor  what misbegotten changes somebody made after 
>misunderstanding the  intent of the code at a later point. Source code 
>tells you what  *actually* happens, not what is *meant* to happen. Anybody 
>that tries  to tell you that the code does exactly what it it supposed to 
>is  almost certainly lying.
>
>Comments in methods ought to offer some help in decoding the  expectations 
>for the method as a whole, or for parts of the method.  Class comments 
>ought to offer a somewhat higher level view of what  the class is supposed 
>to do and the limitations it is known to have.  Other forms of comments and 
>documentation are needed to give later  authors some hope of being able to 
>use, maintain and improve the  system. You need tutorial type documentation 
>to offer newcomers to a  part of the system a chance of getting some sense 
>of the system  before they can even begin to understand the actual code.
>
>Adele Goldberg expressed it once as "if the code isn't documented, it  
>doesn't exist" since without reasonable doc there is no way to count  the 
>code as usable in the long term. I tend to add the corollary  clause "and 
>if it doesn't exist, what did we pay you for?"
>
>Another old friend of mine has also coined the rather nice idea of  
>"program the document, don't document the program" to cover a concept  of 
>merging doc and code in the tools so that you can write spec,  explanation, 
>commentary, examples and limitations mixed in with  executable code. It's 
>not hugely different to some aspects of the  late Jef Raskin's idea of The 
>Humane Interface (see http:// www.raskincenter.org) and it wouldn't be too 
>awful implemented as a  nice document editor that has a style for 'source 
>code' that actually  means source code rather than just using a fixed pitch 
>font. Hmm, now  where might we find a document editor with intimate 
>associations with  a compiler?
>
>tim
>--
>tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
>A)bort, R)etry or S)elf-destruct?
>
>
>