Hi David!

David wrote:
[SNIP of ramblings :-) about documentation]
> I'll apologize again for asking stupid questions like the ones above,
> and now I'll sit down and be quiet.

Those of us who have been in the community for some time, and I am not
sure how long you have been here, tend to feel that people asking the
community to "change" or to "Hey, you should do *this*!" don't really
understand how this community works and generally gets little attention
and might even piss people off. ;-)

Let me be very frank and very disillusioned for a few seconds:

1. There have been A LOT of efforts starting to document Squeak. They
all seem to "fade away". Nothing wrong with trying though - just don't
think it hasn't been done before! Really. I am not kidding.

2. People do what they like to do. Coding is fun. Documentation is not.

3. Even though it is a harsh and perhaps annoying mantra - the "Ok, then
why don't *you* do it?" logic still applies. Talking doesn't count for
much.


Ok, given the above - what can then be done that will actually have a
slight chance to *succeed*? My take on this (which of course may be
totally off) is:

- Whatever you try to do, do it *yourself*. Don't try to talk others
into it. "If you build it, they will come". This is at least my
experience with SM.

- Documentation is all about keeping it fresh. I have earlier proposed
to try to bind documentation with the Unit tests. I still think it is a
great idea (check archives to see what I mean). In other words, the docs
must be tied to the image and tha packages, it can't live on its own. SM
is of course a pillar to lean on in this case. IMHO class comments
belong with the class - not on a swiki.

- As with most things accepted in the community it very often comes down
to good tools. SM is successful, but didn't render much interest until
the Morphic package tool came onto the scene. BFAV has been successful
becuase of similar reasons. The Magic Book concept (see Swiki - and how
ironic? :-)) I sketched on earlier is based on this idea.

So... in short:

If *you* build *The Magic Book* tool and incorporate ideas to tie stuff
with Unit tests or similar mechanisms that ensure things don't get stale
- *then* something might happen. :-)

My 2 cents, Göran