Thanks Benjamin, I was starting to get worried. :)

But the case of seaside is a great example.  The guys doing that are pretty 
busy
writing code and contributing to the community.  If they don't want to stop 
and
write some doc I can understand, but how do other communities handle this?
Can we give the documentation task to someone else?  It wont be as efficient
as if the original developer wrote it, but it would get done at least.

This could be something new users (like myself even) could do to help the
community, learn the systems better and contribute before they are ready
to start releasing code.

>From: "Benjamin Pollack" <benjamin.pollack at gmail.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 16:11:15 -0400
>
>On 8/30/06, Hiren Thacker <hithacker at gmail.com> wrote:
>>
>>actually many seniour Squeakers r thr always on #squeak at
>>irc.freenode.net or asking on mailing-list also get very quick reply
>>usually.So i think we can ask, to author or anyone who knows, about *why*
>>you did it the way you did usually.
>>
>
>There are three possible responses when someone makes a complaint: you can
>address it, you can argue that it's invalid, or you can attack the
>complainer. I suppose I'm happy that everyone's doing the second rather 
>than
>the third, but I'd rather we were doing the first.
>
>J J is entirely correct. There needs to be more documentation. Smalltalk is
>extremely readable, and experienced developers can generally figure out
>fairly quickly how something works through the Message Finder, Senders
>Of/Implementers Of, etc., but that ignores the fact that I shouldn't have 
>to
>do that. What takes me and everyone else an hour each of spelunking through
>the bowels of the class hierarchy would've taken the original designer 
>about
>thirty minutes to summarize in a few paragraphs. Those paragraphs should
>focus on both what and why, and the interplay between those. Even if that
>documentation is slightly inaccurate, if it at least gives me an insight
>into the mind of the original developer, my code exploration can be faster,
>more focused, and more rewarding.
>
>To take a specific example because I know about it, we routinely get
>questions on the Seaside list about the difference between the legacy
>renderer and the newer canvas renderer, because there is no real
>documentation about what problem canvas was trying to solve, how it goes
>about solving it, what the abstraction is that allows pluggable renderers,
>whether the user might want ever to write his own renderer, why canvas is
>still not the default renderer even though nearly all the libraries require
>it, or half a dozen other small points. You can answer the how and what by
>googling the mailing list (if you're lucky enough to use the right terms) 
>or
>by plowing through the voluminous source code and test suites. Even if you
>do both, though, you still might miss very basic facts that are basically
>undocumented if you don't happen to hit just the right email message or 
>look
>at just the right method in your search. (Either #text: or #with: must be
>the last message sent, for example, or unexpected things happen.) 
>Meanwhile,
>if you want the why of canvas, you really need to find a single email from
>Avi from I-don't-know-how-long ago where he announces that a nascent
>WAHtmlCanvas will be included in an upcoming Seaside 2.5 alpha release and
>explains in terms that are perfectly clear to Seaside 2.3 hackers why the
>newer library will be better. The chance of a new user finding that email,
>let alone truly understanding and internalizing its meaning without already
>knowing Seaside, is very low.
>
>This problem is obviously not unique to Seaside; thanks to the Seaside FAQ
>and walkthroughs, Seaside is actually in much better shape than some other
>packages. I'm harping on it because I'm familiar with it. The problem runs
>throughout many libraries both in the core of Squeak and in the full image.
>
>Hiren proposes you simply email the list whenever you have a why. That's a
>waste of everyone's time. The developer has to explain more than once, 
>while
>users who subscribe to the list have to either preemptively save and
>categorize important emails or else try to remember enough words from the
>email that they can google their way to it--and frequently, they give up 
>and
>ask again anyway. New users, meanwhile, are too scared to ask questions on
>squeak-dev, which is where you'd have to ask if you really wanted the
>original coder to respond with a because instead of a more experienced user
>to respond with a how-to.
>
>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


>