<div>"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.</div>
<div><br></div><div>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.<br>
<br></div><div>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,</div>then there is a pretty good chance that you don't know how it works.<br>
And if you don't know how it works, then there is a pretty good chance<br>that it doesn't ;-)" --dtl<div><br></div><div>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.<br>
<div><br><div class="gmail_quote">On Sun, May 2, 2010 at 3:58 PM, David T. Lewis <span dir="ltr"><<a href="mailto:lewis@mail.msen.com" target="_blank">lewis@mail.msen.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>On Sun, May 02, 2010 at 10:16:48PM +0000, Hannes Hirzel wrote:<br>
> Thank you David for this contribution. I assume the class comments are<br>
> in there. We just do not see them in the diff...<br>
<br>
</div>Yes the class comments are in the updates. Actually, this illustrates<br>
a very interesting artifact of Monticello. The creator of Monticello<br>
was not very interested in class comments, as you can plainly see by<br>
browsing the actual Monticello code. This seems to have created a<br>
"blind spot" with regards to documentation, as Monticello browsers and<br>
tools do not even bother to display any changes to class comments.<br>
<br>
This highlights two areas in which documention improvements are badly<br>
needed:<br>
<br>
First, the Monticello classes themselves are a vast wasteland of<br>
undocumented functionality in a very important part of the system.<br>
I really don't know how most of this stuff works, and I'll bet that<br>
I am not the only one who is confused. Adding class comments for<br>
Monticello classes would be very helpful.<br>
<br>
Second, with respect to the tools, fixing Monticello to display<br>
changes to class comments both in the browsers and in the diffs<br>
posted to the mailing list would be a Really Good Thing. If we<br>
don't have this, then we lose visibility for changes to the<br>
comments. Personally, I think that the comments are just as<br>
important as the actual implementation, so any changes to<br>
comments should be just as visible as changes to the code.<br>
<br>
Dave<br>
<br>
<br>
</blockquote></div><br><br clear="all"><br>-- <br>Casey Ransberger<br>
</div>
</div>