Hi folks!

I am not sure anyone is reading this thread anymore (pretty long),
especially since it is one of those yearly
let's-talk-about-documentation-discussions. :)

But I would like to remind you about an idea I floated a while back
(2003): The Magic Book.

First of all - regarding reference docs - as Tim says *external*
reference documentation for the classes is a no-no. And I am not saying
this because it would be bad to *have* :) - I am saying this because I
have been around long enough to realize it is a fruitless path for this
community to try *producing and maintaining it*. In short - there is no
way in HELL that such an external documentation would be kept up to date
with the code.

Reference documentation (class comments, method comments, method
categories etc) should be *part of the code* ensuring that it at least
stands a *chance* of being kept *somewhat* updated. In fact, again based
on years of experience, the only thing I personally ever demand of
codevelopers is that they maintain a reasonable class comment. I don't
even care about the style or format, just make sure it is there - at
least for the "important" classes.

That said - feel free to use Dandelion to generate external HTML (or
other formats) references in abundance, just don't think it will solve
our problem. Like this (I presume Dandelion was used):
http://www.oldenbuettel.de/squeak-doku/

Now, back to the Magic Book idea. The issue with documentation in
general is that it is not intrinsically *coupled* to the code. What I
mean is that you can change one (code or docs) without affecting the
other whatsoever. This is the basis of why docs always go stale - and
even if it isn't stale, I would never trust it *not* to be! And that is
an important observation. Even if there was reference documentation
generated in HTML for Seaside I would not trust it - because I know how
fast Seaside develops and I would never be sure it actually tells me the
truth.

The Magic Book idea came from the realization (after numerous rants to
get people to write unit tests from Stephane Ducasse :) ) that one of
the grand properties of unit tests - as being a form of documentation
(unit tests can often be used as example code) - is that they *are*
coupled to the code. If the code breaks the "external contract" the
tests break. And if the tests are modified - meaning that the "external
contract" is changed - the code possibly breaks. So a unit test can be
seen as an "external contract" of the behavior/API of one or more
objects.

Hmmmm... could we use this as a way of making documentation coupled too
perhaps? I think so. Imagine a book with chapters - each being a
tutorial, howto or introduction to a part of Squeak - and then imagine
every such chapter referencing one or more unit tests for the part it
describes. Each chapter typically describes how to *use* some objects -
in other words - it depends on the external behavior/API of those
objects. See how the unit tests come into play?

Now, if the unit tests for a chapter are green - everything is dandy. If
the tests go *red* (code was changed so that it no longer follows the
contract) or if the tests are *modified* (the contract was modified and
possibly the code too) we automatically flag the chapter as
Needs-review-and-possible-update. A flagged chapter may very well still
be valid - but at least this is a heads up to both readers and the
authors - it *may* have gone stale. And more importantly - if a chapter
is NOT flagged, then I would probably actually dare to trust it. :)

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.

Ok, this is probably the third time I describe this idea - it even has
its own page on the Squeak Swiki:
	http://minnow.cc.gatech.edu/squeak/3004

Perhaps it soon is time to actually implement it. :)

regards, Göran

PS. Anyone recall when people started writing reference docs for classes
on the Squeak Swiki? Or even further back, anyone recall the squeakdoc
swiki? (http://minnow.cc.gatech.edu/squeakdoc) or perhaps you recall...
enough. I guess you get my point. I am even "guilty" myself of such
fruitless endeavours - like the class comment challenge for example. I
am more and more certain that the "only" way to change our collective
behavior is through *tools*. Just look at SM, Monticello, SqueakSource
etc. Tools can be used to coach or provoke behavior. Postings to this
list typically can't... So over and out. :)