Thoughts from an outsider

Benjamin Pollack benjamin.pollack at gmail.com
Wed Aug 30 20:11:15 UTC 2006


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20060830/a5b34fe9/attachment.htm


More information about the Squeak-dev mailing list