[DOCS] Project "Magic Book"

goran.hultgren at bluefish.se goran.hultgren at bluefish.se
Tue Feb 11 12:42:10 UTC 2003


Hannes Hirzel <hannes.hirzel.squeaklist at bluewin.ch> wrote:
> goran.hultgren at bluefish.se wrote:
> > Personally I think it should *not* be webbased. :-) I would like all the
> > documentation to be accessible from inside Squeak in an integrated
> > manner using all the multimedia skills that Squeak has. 
> 
> I consider it to be a valuable mid term goal to have better
> documentation
> within the image. 
> But as a short term goal cleaning up and updateing
> http://minnow.cc.gatech.edu/squeak
> is the easiest thing to do. It just take a little more effort than
> writing emails.

Oh yes, sorry if it sounded like I disagreed with that - I agree *very
strongly* with that. :-) I was more commenting the "end goal".

> > For example -
> > look at the TableLayout Project describing as an interactive essay how
> > that works. (Don't have alink right now)
> 
> That you don't have the link proves that this kind of documentation is
> difficult 
> to access. Why not include this good essay in the image? (Of course with

I am sorry - I knew it was on SuperSwiki somewhere but had forgotten
that Hernan Tylim actually put it on SqueakMap the other day! :-)

So knock yourself out:
http://map2.squeakfoundation.org/sm/packagebyname/TableLayout

> a possibility to get rid of it).
> Did somebody check recently if it loads
> fine
> in Squeak 3.4? We could have a documentation switchboard project 
> within the Squeak image which links to essays like this and is
> regularily 
> maintained.

This last paragraph almost sounds like my current notion of the "Magic
Book".

I have an idea about the Magic Book implementation that I will try to
outline later today involving Projects, StarBrowser and SqueakMap. Well,
some of you may already see what I am getting at by mentioning those
three words... :-)

 > > And I also strongly would consider the
> > link-documentation-to-the-unit-tests-idea in order to automatically
> > detect stale documentation.
> 
> Surely nobody objects that links from the documentation to the
> unit tests are a good idea. The problem is doing it. To automatically
> detect stale documentation is probably science fiction. 

No, it is *not* science fiction! And I wasn't talking about "hypertext
links", I am talking about a real dependency link. The idea goes like
this:

- Pick a class you want to write a tutorial about, say the class Date.
- Write the tutorial and then link the tutorial as "dependent" (not in
the package sense) on the current version of the Date class unit tests.

Voila. Whenever the testcode is changed (new version) or the testcode
isn't green anymore then the tutorial needs to be updated because it has
gone stale. Or at least there is a very good chance it has.

The idea is that the Date class can evolve without turning the tutorial
stale because the tutorial is about *using* the Date class (think
"external contract").

And the unit tests for class Date are also exactly capturing the
"external contract" of the class Date. So if the tests are changed or
doesn't turn green this surely can only mean that one of the following
things have happened:

- There was a bug in the test code that someone fixed. No external
contract changes. False alarm, tutorial is still ok.
- The tests has changed which implies that the external contract of Date
has also changed. Alarm. Tutorial probably needs change.
- Date is changed so that the external contract changed - the tests
fail. Alarm. Tests should be rewritten and so should probably the
tutorial.

Anyway, you get the picture.

> > All this does *not* mean that it shouldn't be collaboratively editable
> > etc.
> So let's go back to swiki editing ....

Right! :-)
 
> Hannes

regards, Göran



More information about the Squeak-dev mailing list