Documentation frenzy, some advice and a history-check...

Hi folks!

I must admit that I have been slightly exhausted from skimming the later
threads on documentation, literate programming etc etc.

I have several detailed reflections I could share - but I don't have
time at this very moment. BUT... Never mind the history about the URL
below (I can explain it some time), but this is a "reminder" that the
issue of documentation (and tons of other issues) are already well known
stuff in the Squeak community (as you probably know - but humour me):

        http://swiki.krampe.se/castaways/2

The above list of "Things burning" was compiled mainly by me in early
2005 (and I gathered lots of it from Ned Konz's great writeup about our
problems), and most of the issues have been known much longer than that.
And discussed to death already of course, we like talking a bit too much
here on squeak-dev :)

A few important words to you newcomers (and feel free to ignore them if
you already know all this):

1. The absence of reactions from most of us "oldtimers" is not lack of
interest or that we ignore you. It is more like "yeah, we know and we
are even tired of discussing it because we have already heard all these
arguments before.". This does not mean that we do not applaud efforts -
it just means we tend to remain skeptical until real results are
delivered. As we all know, talking is easy. :)

2. Dig, dig, dig. The Squeak Swiki has TONS of stuff on these subjects.
And the Squeak-dev archives should be piled full too. You already know
this I am sure.

3. The Squeak community is really friendly, gifted and in short very
nice. Please keep down the "I know the correct answer and you are
wrong"-tone. Even if you are 100% sure you *are* right. This you already
know too of course. :)

If I should end by giving a SINGLE generic advice regarding the kind of
documentation we are discussing here it would probably be this:

Do not do it "outside" of Squeak. It *will* rot. It does not matter how
much you promise to keep it up to date. :) Several have gone before you
and promised that too. And it has rotted. Perhaps not the first year, or
even the second. But are you still keeping it up to date in 5 years?

And even if it is *not* rotten - how does the reader *know* it isn't? In
short - documentation is really nice *if* it can be trusted. And *that*
is what we should try to find a mechanism for IMHO:

        http://minnow.cc.gatech.edu/squeak/3004

Then of course you can do the "simplest thing" that gives a bang for the
buck tomorrow:
        1. Write unit tests for existing code in the image and push it into the
image. It helps a lot.
        2. Write class comments for classes in the image that are either not
there or bad. It helps a lot.

Both the above contributions can be done by most people AND are not
controversial to get accepted.

:) :)

regards, Göran