[DOCS] Project "Magic Book"

Hannes Hirzel hannes.hirzel.squeaklist at bluewin.ch
Sat Feb 8 21:22:57 UTC 2003

Hi Shane,

shane at shaneroberts.com wrote:
> 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.
Well I was rather thinking of deleting outdated paragraphs rather than
deleting pages.
Outdated but for historical reasons important information could be moved
to either general pages
like "Archive 2003 Feburary" or just "page title (archive)".

> 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.

Yes ....
> 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.

I would suggest of refurbishing the Swiki first and then copy the
information into
some structures within Squeak. The Swiki has the advantage of beeing a
collaborative workplace - easy to access, people can participate without
signing in
we can call for the help of specialists with ease and the info is kept
For this kind of task the mailing list may be considered rather as a
change log
while the results are kept in the Swiki.

> In particular I think the "magic book" has the potential to introduce naïve users
> and new developers to Squeak in an exciting way.

I agree. But this is rather a matter of form than content. And before
that we need to have
the content first.

As Stephane Ducasse mentioned in another mail unit tests are a good way
to document.
But this need already quite detailed knowledge. I'm thinking more of
general information
for first time users and explaining concepts.

As you are a newbie, where would you suggest that we should begin?
(Content wise -
a list of questions / tasks would be helpful; please look at the FAQ on
the minnow swiki.
It contains about 60 questions which is not a bad start.


More information about the Squeak-dev mailing list