The idea of a "Magic Book" inside Squeak acting as both an introductory
documentation for Squeak and as a reference manual is quite intriguing.

A few basic ideas that got this started:

- Tying unit tests to documentation in order to detect stale
documentation
- Not bloating the image
- Easily maintain the book cooperatively (like swiki)

Ok, what would be the STTCPW? (For all you non XP aware: "Simplest Thing
That Could Possibly Work").

By applying reuse - what do we already have? We already have:

- Projects: A very good format for "active content". I am not sure how
easily they are backwardscompatible though. Could anyone post some
insight in that matter?

- StarBrowser: A universal UI kindof thing. We could easily let
StarBrowser be the main UI of the Magic Book! It lends itself easily for
the task - a treeview on the left, a dynamic area to the left etc. If we
somehow find a good way to integrate a little search form then it would
be quite perfect.

- SqueakMap: In whichever form we choose to have the Chapters of the
book (Projects) we could register them on SM (a few new categories would
be nice) and thus get a distributed always up to date model of chapters
for free. And when SM1.1 gets completed it will track versions of the
chapters for us, etc. And in SM1.1 it will have a sensible smart
diskcache for the packages (read Chapters) so we get that too.

- Free text engine: Scott Crosby wrote a neat little engine for
maintaining keyword indices that the book obviously should use. I have
also been intending to integrate that into SM. We should be able to add
it to SM in such a way that the Magic Book can simple get that "for
free".

So... we already have a bunch of cool technology to implement the Magic
Book IMHO. We just need to knit it all together in a smart way.

If we split the book in the following pieces:

1. The TOC. This is essentially a list of chapters organized in a
hierarchy with names and a link to the corresponding SM package that is
the chapter content - a Project.

2. The chapters themselves. These are simply Projects published as
packages on SM. Perhaps we need to follow a few conventions for these
Projects so that we easily can "jump into" them in a proper manner,
extract keywords for indices etc.

3. The search indices and the index (as books have last).

If 1 and 2 above also are packages on SM (in whichever suitable form,
doesn't matter) it will be even more simplified. So the book *contents*
are then managed as packages on SM. We get the possibility of having
different owners for different chapters, release/version tracking etc.
It is obvious when you think about it - why shouldn't they be packages?

The StarBrowser is the obvious choice of a UI - it already has
navigation mechanisms and it can also show contents from the book along
with other things in a highly dynamic fashion. Why reinvent that?

And SqueakMap gives us a lot of stuff like efficiently always updated
content, a smart cache etc.

And there will be no image bloat whatsoever.

Well, ok, what do you all think? Darn, this sounds like real fun... I
need to get cranking at my SM1.1 ... :-)

regards, Göran