Documentation [was: Morphic tutorial]

Brent Vukmer bvukmer at blackboard.com
Thu Feb 13 15:54:26 UTC 2003


I am exuberantly hopeful that good, package-version-specific
documentation will become part of the Squeak environment and community.
I believe that the primary need right now for documentation is more
people/process/habits-oriented than technology-oriented.

I am very hopeful that the documentation effort will gather a lot of
momentum, in the same way that SqueakMap did.  We'll see.  It will only
take off if people get excited about it and help get things moving...
As far as documentation team goes, the team is doing the simplest thing
first -- updating the Swiki.  We are "harvesting" documentation snippets
from the list -- Hannes Hirzel has been working like crazy on this!  Go
Hannes! -- and adding it to Swiki pages.  Yes, this is dead simple.
Yes, this documentation is neither in the image, nor packaged for
download.  And, yes, it could get stale.

However I think the key thing we need to do right now is build momentum
by getting more and more people involved. I want DOCS
goodies/enhancements/fixes to be posted to the list as often as
changesets get posted to the list... :)   If we get the ball rolling
with lots of doc. updates, we can improve the harvesting and updates
processes for documentation.  Then, we can work to sync those processes
with the harvest and update processes for packages and the main image.  

At some point we will start working on putting the documentation inside
Squeak.  It makes sense, we need to do it.  There will be a Magic Book
( and perhaps a DocBrowser, too ).   


Now, back to fixing bugs in Java at my day job..
BKV

 
-----Original Message-----
From: goran.hultgren at bluefish.se [mailto:goran.hultgren at bluefish.se]
Sent: Thursday, February 13, 2003 4:27 AM
To: The general-purpose Squeak developers list
Subject: Re: Documentation [was: Morphic tutorial]


"Richard A. O'Keefe" <ok at cs.otago.ac.nz> wrote:
[SNIP]
> The next time someone says "let's make a Swiki page to talk about
> documentation" I'm going to vomit.

Well then, Mr O'Keefe - why don't you help out then? You are a very
competent Squeak programmer - perhaps you could help us realize the
"Magic Book"? And if you don't have the time to help then... well.

Squeak suffers from lack of a good multi developer source management
system (which should of course include documentation) and lacks a good
process for dealing with it (Harvesting has great problems). We all know
this painfully well.

But we are aiming to solve these problems. Harvesting will change
dramatically once we have the new tools set up for that. SqueakMap has
already changed a lot. And the Magic Book could do the same for
documentation inside the image.

So while I can sympathize with your comment (good knows I can) it is
still a rather stupid comment to post in an open source project. In My
Very Humble Opinion.

regards, Goran




More information about the Squeak-dev mailing list