Hannes,
this is great.

I'm not familiar with the term "minnow swiki" is that the same as 
http://minnow.cc.gatech.edu/squeak?

I think we have to be careful about "archiving" the swiki pages, because I notice
they are often referenced by members of the list, and we could produce a lot of
broken links in people's email if we remove pages (or rename their URL).
But perhaps your suggestion of a nomenclature for page titles could be used to
classified "new" and "archived" pages.

I am new to Squeak and Smalltalk, but I have now discovered (with Goran's 
encouragement) that the Swiki is VERY useful.

So I agree the Swiki should be maintained, upgraded, and used.

But I also agree with the suggestion that embedded documentation in Squeak is 
preferable, and that of course we need to improve code comments, etc.
In particular I think the "magic book" has the potential to introduce naïve users
and new developers to Squeak in an exciting way.

Shane

On 8 Feb 2003 at 18:54, Hannes Hirzel wrote:

> 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