Considering the supposed emphasis on using Squeak as a teaching tool,
I guess I find these reasons to be a really poor excuse. What good is
a great tool to the public as a whole if the only people who can use
it are the developers?

The lead developers need to make development of good documentation
just as central to releases as the code itself. Until they demand that
documentation be completed and updated before software is released, it
won't be. The lead developers need to take charge of the documentation
process instead of allowing themselves to let others take this "chore"
off their hands. The attitude I'm seeing here that the documentation
is a necessary evil that must be "grinded out' sounds like it very
well could be a significant part of the problem. Writing can be fun to
do if you go about it in a light-hearted fashion and that type of
writing also engages the reader.

Personally, I know a bit about writing, but I know nothing about
programming.  I'm a programming newbie that would really like to learn
Squeak, but I'm pretty much kept from doing that because of your
current documentation situation. I read this list because I keep
hoping I'll read some new focused learning resources have been
created. So when I read that many feel "coding is fun, documentation
is not" on the threads, it doesn't do much for my confidence that I'll
ever get the chance to use Squeak.

If you guys really want to be the Squeak evangalists you seem to all
claim you want to be, you're going to have to have a complete attitude
change about things like complete centralized documentation and the
creation of Squeak programming texts for those new to programming.






--- In squeak at yahoogroups.com, goran.krampe at b... wrote:
> 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