>From: "Ramon Leon" <ramon.leon at allresnet.com>
>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 12:19:52 -0700
>
>
>I don't measure success by the number of people using Smalltalk.
>Personally, I want Smalltalk to be for people who grok Smalltalk, not for
>people who want to make it more popular by making it more like everything
>else.  Smalltalk rocks precisely because it's not like everything else, and
>that includes what is considered programmer documentation.  Self 
>documenting
>code is a style, one smalltalkers prefer, that and some unit tests, are the
>best documents there are.
>

I don't want smalltalk to be like everything else.  But I do want
language choice where I work, and that doesn't happen if the
language doesn't have a very big user base.  I don't think actually
documenting your work will turn smalltalk instantly into Java.

> > I just don't find "code is the documentation" acceptable at a
> > professional level.  Open software tried to say that in the
>
>Ok, maybe you don't, but many others do.  There's lot's of stuff being done
>out there in Smalltalk land with little or no "formal" documentation.
>Documentation the way you define it, simply isn't necessary for success,
>maybe it's necessary for mass accpetance, but acceptance and success are
>different things.  Smalltalk is already successful, and growing more so
>every day.
>

Well I certainly hope it gets more sucessful every day.  It certainly
deserves it IMO.

> > But if my company has millions of dollars riding on your
> > software there had better be some documentation.
>
>That's an opinion, not a fact, but there's plenty of code out there running
>on Squeak, and very little if any formal documentation.  Success depends on
>people, not paperwork.  You'd be trusting millions of dollars to a person,
>or a team of people, not some papers.
>

Yes, but that isn't the issue.  The issue is what if you guys leave?  If we 
have
nice, up to date documentation of the system the team I have to get to
replace you doesn't have to take as long figuring out the system.

> > Do really think it would be ok to deliver a product to a
> > customer and say "well, the code is all there, dig around and
> > you should be able to figure out how it works in no time"?
>
>I thought we were talking about documenting code for programmers, not user
>documents for products.  Was I mistaken?
>
>

No you weren't, but I see the two things as close to equivalant.  If you 
wouldn't
give software to end users with no documentation, how could you consider
it ok if your end users happen to be programmers?  I mean, in the case of
a subsystem you are delivering an API, but I want to understand what it
does without having to basically read the entire code.

I relize smalltalk code writers write small methods, and that is good for 
the system.
But it takes me more time if I have to look up how a method works because 
the
first method (or 3) wont actually be doing the work.