[ANN] Squeak Documentation Team formation

goran at krampe.se goran at krampe.se
Fri Sep 22 06:51:29 UTC 2006


Hi Matthew and all!

First of all - great initiative! I will try my hardest to support and
help as time permits. And it is really good that you make this effort
"official" through the Team model - it gives it all much more "weight"
and makes sure that we slightly disillusioned oldtimers actually open
our eyes. ;)

Matthew Fulmer <tapplek at gmail.com> wrote:
> > Matthew: is your quest to build a team to create Squeak educational
> > projects - such as "Newbie-Tutorial.pr", or to create documentation?
> > While they overlap, their focus is quite different.
> 
> Thank you for pointing that out. My intent is to create a
> textual tutorial on the Swiki or elsewhere. I believe I can
> handle that task.

And I think this is "smart". As Bryce said on the chat - a tutorial is
probably what gives most "bang for the buck". (well, he said something
similar)

As you note in your plan, two side effects of this project are:
	- Indexing resources we already have. Can't be wrong, even though the
index eventually probably will turn unmaintained (devil speaking from
experience) ;)
	- Add/improve existing class comments as the team members learn about
stuff. This is IMHO the best aspect of your plan!

If this team, while writing the tutorial, produces class comments that
are non existent or bad today - then that will be a REAL tangible
result. And they will enter the image and thus be *somewhat* protected
from getting lost and unmaintained.

Now, let me ask a really annoying question: What will happen with this
tutorial after year 2008?

If the answer is - "dunno" - then that is perfectly fine of course. I
just want people to realize that many tutorials have in fact been
written over the years and AFAIK *ALL* have turned stale. Feel free to
point me to an up-to-date maintained Morphic tutorial and prove me
wrong. :) So some kind of planned antidote for that grim future would be
nice to have - whatever that would be.

> I think that a live tutorial is the focus
> of the non-existent Magic Book project:
> http://macos.tuwien.ac.at:9009/998031382.asHtml

Actually, that is not the focus of the Magic Book - at least not as I
have imagined it :).
If you read that posting carefully (and I think it is worth reading) it
says:

	"The actual book would imho best be written as a Morphic tool with the
	ability to have the actual chapter contents loaded on demand in
multiple
	formats - HTML, wiki text, Morphic code, Morphic projects, whatever.
And
	each chapter could be a separate package on SM having separate
	maintainers etc. It could spawn an external browser for HTML chapters,
	it could show Morphic content directly, it could spawn an external
	browser for wiki contents etc, etc."

This means that the Magic Book itself is just a regular Morphic tool and
that the content can be of many kinds - the simplest being plain old
ugly text (and not at all a live tutorial). Darn, I am really itching to
write that tool... :)

regards, Göran



More information about the Squeak-dev mailing list