Documentation... (was Re: Article in Wired)

Lex Spoon lex at cc.gatech.edu
Mon Jun 7 12:54:42 UTC 1999


In addition to documenting the individual class and methods, let's not
forget the benefit of big-picture kind of documents.  For example, a
discussion of how printOn: and its friends work would probably be a lot
more insightful to a beginner than individual documentation of the 130
individual implementors of that method.

In fact, once you have an overview of how some code works, I expect you
may as well just browse through the actual code to get the details.  Is
it really worthwhile typing in "print the object onto aStream" for all
130 implementers of printOn:, if you already know what printOn: is for?

Of course, an intriguing way to do this has been made available to us by
the Squeak team: use Squeak pages to do the documentation!  The details
of this, however, remain to be worked out....  

Perhaps in the interim, it would be good for us to start gathering
documentation that already exists, and provide a place for more
documentation to be added?  I'm reminded specifically of the Linux
Documentation Project, which collects all kinds of odds and ends
together into a wonderful resource for learning about Linux.  It should
work for Squeak, too.  And a lot of this stuff exists out there
already--it just hasn't, to my knowledge, been brought together
anywhere.

Anyway, here's some ideas for "big-picture" essays that I think would be
quite helpful:

	- code browsing techniques, ie using the browsers, looking at
implementors-of, and such
	- using streams (next, next:, upTo:, ...)
	- defining new streams (how to recognize a stream-like class, which
methods to override,...)
	- using collections (do:, the wierdo select:/collect: methods, add:,
remove:,...)
	- the relationship between streams and collections, eg Stream>>do:
versus Collection>>do:
	- printOn: and family

	- morphic graphics
	- using those wierd looking halos  :)
	- working with changesets and projects

	- objects versus classes

	- each of the neato toys that gets put out, could also probably use a
few pages.  at this point i'm as guilty as anyone else  *sigh*


Some of these might still be too big, but the basic idea is not to
include all the details, but instead to point out the things that are
really important.  


Lex



"Peter Smet" <peter.smet at flinders.edu.au> wrote:
> Perhaps we could pull ourselves up by our own bootstraps
> here and use dandelion to produce a nice HTML formatted
> class hierachy. This could constitute a make-shift reference
> manual. I agree the html document would still need comments
> and examples, but it's a good start.
> 
> Peter
> 
> 
> >I think it may be worthwhile to stop madly coding for one or two
weeks and
> >just comment all the classes you've all designed.  It would probably
> >improve coding efficiency since most coders will not know the entire
Squeak
> >hierarchy and may need to use something they have never encountered
> >before.  Although they could probably just study the code and figure
it
> >out, it would probably be a whole lot easier with a simple example
that
> >describes the operation in detail.
> >
> >(I've gotta start commenting my classes too! :)
> >
> >-- Dino
> >
> >





More information about the Squeak-dev mailing list