[DOCS] Project "Magic Book"

Stephane Ducasse ducasse at iam.unibe.ch
Sat Feb 8 18:10:31 UTC 2003

Hi hannes

I agree that documentation is difficult. Now focus on having a class 
comment on each class with two examples. This would be great.

I still think that writing SUnit tests is the cheapest way for 
documentation (that will stay in sync with squeak) and the future of 
Squeak because it will support the refactoring and the harvesting 
process. My books are in english but I do not think that they are good 
for documentation.

So good luck with external documents.


On Saturday, February 8, 2003, at 06:54 PM, 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
Prof. Dr. Stéphane DUCASSE (ducasse at iam.unibe.ch) 
  "if you knew today was your last day on earth, what would you do
  different? ... especially if, by doing something different, today
  might not be your last day on earth" Calvin&Hobbes

More information about the Squeak-dev mailing list