Documenting Squeak

Alan C. Kay alank at wdi.disney.com
Sat Mar 28 18:01:07 UTC 1998


Folks --

I feel very positive and supportive of both suggestions. Our motto is "The system is the curriculum", but we have yet to make good on this, and appreciate very much everyone's interests and contributions in this important area.

Best to all,

Alan

-----

At 8:04 AM -0800 3/28/98, Stephen Ma wrote:
>Tansel Ersavas <tansel at rase.com> writes:
>> Reinier van Loon wrote:
>> > 
>> > I am more or less busy documenting Squeak using [Paradigm Plus].
>> > [Found a possible inconsistency in Controller re: Sensor]
>> > [Volunteer to maintain a list of similar oddities]
>> 
>> [Describes a nice tool for generating graphical class diagrams in HTML]
>>
>> http://www.rase.com/cybercards/db/ccm.htm
>> (click on the subsystem and class icons in images) 
>> 
>> [Above URL may disappear because it's supposed to be sort of
>> secret, so see it soon!]
>> 
>> The disadvantage of doing all these is in Paradigm Plus is it is a
>> pain, especially to redo parts of it every time the system
>> changes.
>
>I agree.  In my experience, the only way to maintain consistent
>documentation in a rapidly evolving system like Squeak is to attach
>that documentation as tightly as possible to the code.
>
>> ... [snip] ...  although normally this system is for sale
>> for VSE (and soon VA), I'll make it freely available for Squeak
>> community for learning and developing Squeak (I'll still ask people
>> who use it for commercial purposes to buy it though).
>> 
>> When it is ready to be tested, I will let everyone in this group
>> know so that people can download and play with it true to the
>> culture of Squeak.
>
>I'm looking forward to it!
>
>However, Tansel, I have a feeling that even your utility may not be
>enough.  There's also a desperate need for overviews and tutorials;
>these tend not to fit well into Smalltalk's traditional hierarchy of
>classes, categories, and methods.
>
>Hence I propose a "documentation browser", similar in appearance and
>behavior to the system's other multi-paned browsers, which allows
>people to navigate and modify an independent hierarchy of "books",
>"chapters", "sections", and so forth.  There would of course be
>hyperlinks, not only to points within the documentation hierarchy, but
>also to class and method comments.
>
>The documentation browser would sit on the desktop, and would probably
>be the first thing any new Squeaker sees.  If books like "Squeak
>Tutorial" and "Morphic Guide" were this easily accessible, I think
>Squeak would become much more approachable.
>
>Here is a wild idea: why not make the tutorials interactive?  After
>all, we have the full power of Smalltalk behind every page.
>
>What do you people think?
>
>
>------------------------------------
>Stephen Ma <stephen_ma at mindlink.net>





More information about the Squeak-dev mailing list