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