On 8/30/06, <b class="gmail_sendername">Hiren Thacker</b> <<a href="mailto:hithacker@gmail.com">hithacker@gmail.com</a>> wrote:<div><span class="gmail_quote"></span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div><div>actually many seniour Squeakers r thr always on #squeak at <a href="http://irc.freenode.net" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">irc.freenode.net</a> 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.<br></div></div></blockquote><div><div><br>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.
<br><br>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
<span style="font-style: italic;">what</span> and <span style="font-style: italic;">why</span>, 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.
<br><br>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
<span style="font-style: italic;">how</span> and <span style="font-style: italic;">what</span> 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
<span style="font-style: italic;">why</span> 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.
<br><br>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.
<br><br>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
<span style="font-style: italic;">because</span> instead of a more experienced user to respond with a <span style="font-style: italic;">how-to</span>.<span style="font-style: italic;"></span><br><br>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.
<br><br>--Benjamin<br></div></div></div>