"Vast wasteland." Heh. When I first found myself looking perplexedly into a
Squeak image a couple years ago, I felt like an archeologist who'd
discovered the crash site of an alien space craft. On one hand, I had the
sense that I was looking at something (at least in terms of software) which
was very old, and on the other, like I was looking at something radically
advanced in ways I had no context for understanding.

I think I heard a talk in which Avi (who ironically, I think, may be your
"creator of Monticello" heh) referred to Smalltalk as "the monolith." That
comment really jived with what I had experienced when I first looked into
it, in addition to being a great funny reference to 2001: A Space Odyssey.

WRT your comments on the state of documentation in Monticello, "The moral of
the story is that if you can't explain how something works in clear
language,
then there is a pretty good chance that you don't know how it works.
And if you don't know how it works, then there is a pretty good chance
that it doesn't ;-)" --dtl

I worry a little that too few people in the community really grok MC, and it
is a rather large swath of undocumented code that we're only staking our
entire development model on. So I think maybe I will devote some time to
wading through it, learning what I can, and documenting things as I learn
them. Thank you for the suggestion.

On Sun, May 2, 2010 at 3:58 PM, David T. Lewis <lewis at mail.msen.com> wrote:

> On Sun, May 02, 2010 at 10:16:48PM +0000, Hannes Hirzel wrote:
> > Thank you David for this contribution. I assume the class comments are
> > in there. We just do not see them in the diff...
>
> Yes the class comments are in the updates. Actually, this illustrates
> a very interesting artifact of Monticello. The creator of Monticello
> was not very interested in class comments, as you can plainly see by
> browsing the actual Monticello code. This seems to have created a
> "blind spot" with regards to documentation, as Monticello browsers and
> tools do not even bother to display any changes to class comments.
>
> This highlights two areas in which documention improvements are badly
> needed:
>
> First, the Monticello classes themselves are a vast wasteland of
> undocumented functionality in a very important part of the system.
> I really don't know how most of this stuff works, and I'll bet that
> I am not the only one who is confused. Adding class comments for
> Monticello classes would be very helpful.
>
> Second, with respect to the tools, fixing Monticello to display
> changes to class comments both in the browsers and in the diffs
> posted to the mailing list would be a Really Good Thing. If we
> don't have this, then we lose visibility for changes to the
> comments. Personally, I think that the comments are just as
> important as the actual implementation, so any changes to
> comments should be just as visible as changes to the code.
>
> Dave
>
>
>


-- 
Casey Ransberger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100502/d8257d7c/attachment.htm