Documenting Squeak

Stephen Ma stephen_ma at mindlink.bc.ca
Sat Mar 28 16:04:56 UTC 1998


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