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

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
puzzled.

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.

Thanks.

Ross Boylan

Hi Ross,

On Thu, Jun 12, 2008 at 8:23 PM, Ross Boylan <[hidden email]> wrote:
> 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.


squeak-dev images come with some documentation. When you first open an
image, a script manager appears and some info is written here. You can
reopen the ScriptManager from the world->open... menu. However, there
is very few documents.


> 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.


Please submit the bugs to bugs.squeak.org. You have to choose between
two projects: Squeak and Squeak Packages. Choose the first one if it
is related to Squeak itself. You also have to choose the package in
which the bug appears (OmniBrowser, eCompletion...).

> 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?


Someone must write documentation about these icons. David, can you
find some time?


> 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.


Look at the TestRunner class which is a good example of ToolBuilder use.


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


Read Squeak By Example http://squeakbyexample.org/

--
Damien Cassou
Peter von der Ahé: «I'm beginning to see why Gilad wished us good
luck». (http://blogs.sun.com/ahe/entry/override_snafu)

>> 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?
>
>
> Someone must write documentation about these icons. David, can you
> find some time?

ok, I will take care of this.


David