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
squeak-dev@lists.squeakfoundation.org