shane at shaneroberts.com wrote:
> I think Chris Burkert has made a great suggestion for getting
> newbies more quickly integrated into the community, helping them
> learn Squeak, and contributing by writing.

I agree with the general idea. Let me just (as one of the Guides) give
some pointers and some advice/ideas/remarks.

> I volunteer to:
> 1)  coordinate the setup of the Swiki page
> 2) coordinate setup of the squeak-doc mailing list

Both the above can probably easily get done by talking with Cees de
Groot. He is the man hosting both the mailinglist and the SqF Swikis.
BUT... before doing this let me just say a few things:

1. A new mailinglist is probably not the best thing. I have seen
multiple parallell lists come and go over the years (modules etc) and
many of us prefer the simplicity of just having one or two lists to
follow. Currently I follow the SqF list (where the Guides "hang out")
and the Squeak-dev list. My advice is to wait with the mailinglist and
stay here on Squeak-dev until the traffic really gets annoying.
Otherwise you are risking death by suffocation (=no readers) even before
you get rolling. :-)

2. A Swiki intended for just documentation of Squeak has been tried and
failed before. Of course this doesn't mean that it will fail now of
course - I have known to be wrong on occasion :-). There are also today
quite a lot of documentation on the Squeak Swiki. I am not promoting to
simply continue to use that Swiki (well, for starters - but see below
for the Grand Pla), but on the other hand I think that a new Swiki will
compete with the Squeak-swiki (just as the old one did) and probably not
win. Remember that the Squeak Swiki is searchable and that people don't
like searching in multiple places.

So, my advice - take it or don't - are:

1. Stay here on Squeak-dev to begin with.
2. Wait with creating a new Swiki and instead create a Swiki page on the
Squeak-swiki describing the plan and the team you have managed to
"gather" and who is meant to do what. But before you even do *that* -
search the Swiki because IIIRC there have been other similar
documentation attempts started before you...
3. Begin by doing an inventory. What do we have today?
4. Take a deep look at how the documentation should be created. I am
personally a bit sceptical of the use of a Swiki - see argumentation
below.

I don't think that "system documentation" should be outside of Squeak in
HTML or as a printed book. As supplementary formats - sure, but not as
the primary source IMHO.

As with all "separate" documentation it will simply wither, rot and die.
;-) We have seen it before. The same problem actually exists with *code*
outside of the current base image (and this is one of the challenges of
the new world of packages) - code that people don't see inside their
typical image is very easily forgotten and thus will eventually rot
(turn incompatible).

I would rather like to see documentation created inside Squeak - I mean,
hey - Squeak is a superb multimedia environment where stuff can be
demonstrated and interacted with. And I would bet on the fact that Alan
agrees with me on this. :-)

Currently we have class comments, example code and sample Projects (many
on the SuperSwiki). Perhaps we should create some form of integrated
documentation inside Squeak right there together with the code? Yes - it
is the good old idea of Knuth. Documentation separated from the code
will always get stale. The XP people have also re-realized this and
their solution is to simply skip documentation (more or less)! The Knuth
solution was to interweave the code and the documentation so that
neither is separate, thus forcing them to be "in synch".

I would promote something in the lines of Knuth - not by interweaving
with the code perhaps, even though some form of "links" between the code
and the docs is needed in order to keep them "glued together".

Rather a nice interactive "book" in Squeak with a TOC, index,
introduction chapters, search capabilities and integrated runnable demos
would be fantastic and quite plausible.

If I change the code in a class that is used/documented inside the
interactive documentation then I should be alerted or even (more or
less) forced to review the docs too. It is simply *fundamental* for the
success of such an effort that the code and the interactive manual are
kept synchronized.

And finally - HTML and/or printed docs could probably eventually be
produced from this interactive book. But the need wouldn't be that high
of course.

> 3) Administer SwikiDoc
> 4) And write documentation
> 
> How do we get a consus for go ahead on this?

Well, we can start by fleshing out the "plan" a bit more - I like things
to be very concrete. And then if all Guides are "for it" then you could
IMHO take that as "go".

regards, Göran