I would like to thank Michael Haupt, Nicolas Cellier, Hannes Hirzel and
Casey Ransberger for investing their time in this discussion. I agree
with what has been said so far, but perhaps we should step back a bit
and try to define what will be the scope of the documentation and how it
will be presented.

About the who, I fully agree this will be a job for everybody and not
just the Documentation Team. I see a team like this as a group that will
create the necessary infrastructure and might even act as editors, but
the authors are a separate group (it will be great if people want to be
a part of both, of course).

Of course we have methods comments and class comments, but I think there
is no limit to the kind of in-image documentation we can have. And if
the trend is towards a smaller kernel with loadable stuff, the bulk of
this documentation could be in the form of loadable packages. Using the
same tools and proceedures as for evolving the code is certainly a good
option (though this might require extending those tools a bit).

One important feature for the documentation is to make it more easily
available outside of Squeak. I don't like to write the same thing twice,
but imagine that we could create a doc.squeak.org site running a fully
loaded image and automatically exporting all the documentation in a form
that people and web crawlers can use.

These are just some ideas to keep the ball rolling.

-- Jecel