Spreading Smalltalk

goran.hultgren at bluefish.se goran.hultgren at bluefish.se
Thu Apr 18 08:36:09 UTC 2002


"Richard A. O'Keefe" <ok at cs.otago.ac.nz> wrote:
> cg at cdegroot.com (Cees de Groot) wrote:
> 	>2. Produce good reference docs by integrating some form of documentation
> 	>tools in the environment. 
> 	
> 	See PIE comment, above (I think I blabbered about documentation somewhere
> 	on this list earlier this year). Personally, I think we should first to
> 	strive to make documentation available inside Squeak in an optimal way
> 	(books, with all sorts of embedded Morphs) and only think about "legacy
> 	web access" later on. That'll probably provide the right mindset to do
> 	something really great in this area.
> 	
> All of that stuff is cool, but it cannot compensate for the major
> problem.  There is no point in having fancy tools to organise, present,
> and navigate around documentation if the documentation is not _there_.
> What we need is more text.  At the very least a class comment for
> every class, even if it's just "You are not meant to use this class.".

I agree fully (and wrote so in a later post in this thread). But in the
goal of attracting new people to Squeak (reference material published in
HTML form) and in the goal of producing a book (with reference material)
we need some simple tool support to extract and produce that output. And
such tools might (of course) affect how we document the classes.

But (as you can see in my other post) the MAIN problem is missing
comments. Especially class comments. I even wrote a proposal of a
remedy.

regards, Göran



More information about the Squeak-dev mailing list