shane at shaneroberts.com wrote:
> Brent and I (Shane)  have announced our commitment to a DOCS 
> project, as team members.  And specifically to the "Magic Book" 
> idea.
> 
> We are currently awaiting any "me toos" from the list.  If we do not 
> hear from anyone on the list by the end of today, we will move 
> forward as The DOCS Team of Two.


Hi Brent and Shane

Great that you embark on a documentation project. In the past I wrote
quite some pages on the minnow 
swiki on various topics.
I'm aware that the Swiki is somewhat messy but I still think it contains
valuable information
not found elsewhere and I think it is hard to do a good documentation. 
There were various efforts in the past to come up with a better
documentation but they were not acutally successful exactly for this
reason.


The problem of writing documentation
---------------------------------------------

Part of the problem of documentation writing lies  in the fact that
doing documentation is somewhat 
considered to be a ''dummies'' job by many while at the same time in
fact beeing a hard job. 

This includes doing a lot of reverse engineering and second-guessing.

If you begin diggin into the image you soon find that there is a lot of
messy code. Obviously the original programmers
are not to keen in digressing about these issues and for others the
problem is just finding the way in the messy code.

Many people as well think that it doesn't matter as long as it works. I
do not agree. These topics have been discussed back and forth several
times on this list so we should not go into this discussion once more.
We have to live with what is available.  

I'm willing to participate in this renewed documentation endeveaour.
I'd like to concentrate on task oriented / use case oriented issues and
in describing the behaviour of important classes and concepts. 

Just yesterday I looked at an app I wrote 6 months ago and I was
astonished how fast one gets into a Sqeueak app one wrote oneself; it
was possible to update the app in short time.

Perhaps this is an explanation why it is hard to get useful information
from the programmers regarding documentation. They just have no idea
what could be difficult about what they wrote. The problem is that they
have the context information while others have not. They know where to
focus and where to defocus completely when looking at the code. For
example Dan Ingalls: he is now in this Smalltalk business for 30
(thirty) years! (BTW this is nice - this shows that good concepts have a
long life)

My possible contribution: I'm willing to help with documentation as far
as my time permits which is only 8 to 12 hours a month at the moment.
However as I have worked with Squeak for a few years now and then; this
might be a help to you already. And I know that many participants on the
list are willing to help as well as long as the effort does not execeed
2 to 4 hours a month and if they get cleary assigned tasks.





Sources of documentation
------------------------------

Regarding the Squeak minnow Swiki I think we should revamp the thing.
This means for example we should delete outdated things or move them to
history or archive pages. This avoids having to much cognitive clutter.
For example we just could add pages with the name 

aTopic (archive)

if we think that some information of earlier versions should be kept or
to honour contributions of list members but are not important to know
for newcomers. Other things should be deleted completely. 

The German Squeak Users group (actually Marcus Denker) recently did a
Squeak CDROM which included a snapshot of the minnow Swiki and they plan
to do it again. So I think this is a valuable and easy to use ressource
for doing documentation.

As you have mentioned an attractive thing surely is to come up with some
more example projects within Squeak which illustrate certain issues. 

Bobs super swiki contains a wealth of information; although a bit
scattered around.





To sum up: 
-------------

1) I think there is a lot of material flying around, but it has to be
checked again, streamlined and old stuff has to be eliminated.

2) Stephane Ducasse is writing two books which is very valuable  to
promote Squeak. I do not know how far he is at the moment. I'm not aware
if it will be in French or not. However an idea might be to translate it
into English / French / German or Spanish (Stephane are you reading this
?)

But on a more general level I do not think that books are the right
medium at the moment as they get outdated quite fast and it is not clear
what the canonical content is. There are already Smalltalk books in the
libraries.

3) To have documentation within the Squeak image would be very valuable.
This make it more attractive for computer magazines to put Squeak on
their CDs if the out-of-box experience for first time users is better.
Recently for example Lex Spoon mentioned that even an empty project is
missing and he had to explain to first time users how to do it (which is
only simple if you already know where to look and how to do it).

4) It is a good time to do docmentation now as Squeak has stabilized
considerably and we have with SqueakMap a method to cooperate in a
better way as it used to be (additions need not be in the image anymore
while beeing easily acessible - thanks to Goran Hultgren an others -
this keeps the core image more stable.)

Regards
Hannes