[squeak-dev] documentation and bugs (sq-dev image)

Ross Boylan ross at biostat.ucsf.edu
Thu Jun 12 18:23:58 UTC 2008

I'm using Damien's sq3.10-7159dev08.06.1 image, which seems to have lots
of neat tools.  But it doesn't seem to have much documentation on them,
either in the image or on the wiki.  Maybe I'm just not looking in the
right places.  There are also some behaviors that seem as if they might
be bugs.

Taking the possible bugs first, would the best route be to report them
here, put them in the squeak bug tracker, mail Damien, contact the
creator of the package, or contact the maintainer of the package?  I'm
guessing the first, but I'm not sure.

On the documentation, the main system browser ("OB Package Browser") has
all kinds of graphical clues on it, with little icons appearing next to
some items, and some of the items in italics.  What do they mean?

For ToolBuilder, I can't find an explanation of the standard work flow
to use it.  I can probably figure this out from some of the code that
does use it in the image, but it would be nice to have a little
statement what to do.

Similary, though I haven't looked as hard, I haven't found how to use
the unit testing framework.

Some of the Morph's have only auto-generated class comments, leaving one
to guess about their role.  For example, PluggableListMorphByItem does
not even include the original class description that I found on the
mailing list--though, even after reading it I must say I'm a bit

At least some of this information is undoubtedly in tutorials, but it
would be much easier for me to have specific documentation on specific
tools, classes, and functions than to try to hunt through (possibly
dated or irrelevant) tutorials.

I know most programmers don't like to do documentation, but it makes a
big difference in how useable and approachable the system is.  I believe
the  XP recommendation is to write tests before writing the code.  I
think it would be useful to extend that to writing documentation before
writing tests.  I have found it is often a useful exercise because it
reveals problems or omissions in what you were going to do.

Of course, if anyone can fill in the gaps in my understanding or give me
pointers to places that do, I'd appreciate it.


Ross Boylan

More information about the Squeak-dev mailing list