[DOCS] Project "Magic Book"

Tim Rowledge tim at sumeru.stanford.edu
Tue Feb 11 00:05:24 UTC 2003

Ivan Tomek <ivan.tomek at acadiau.ca> appears to have written:

> Wouldn't the XP argument be that writing a (detailed) manual
> (=specification) before implementation is too early? On the other hand, a
> draft corresponding to 'user stories' might be useful, but insufficient.
It probably would be the XP claim that a detailed spec up front
is premature and I'd usually agree. What I'm suggesting is _not_ a
detailed spec of what is implemented and how but rather some reasonably
detailed explanation of what to do to use it; I imagine this would map
very much to the 'user story' idea.

As an example, when I was writing the VMMaker class I had a whole load
of code before I ever tried to explain it to anyone else. As I wrote the
explanation that was eventually published in SqueakNews I learned a lot
about how the 'outer' layers needed writing in order to be usable by
anyone not utterly au fait with the workings of the class.

I believe that if we gathered a good collection of 'user stories' about
UI needs we could learn a great deal about what is good and bad in the
current implementation of Morphic (and probably a lot of the system) and
make a lot of progress towards an improved image. So, maybe 'write
the manual first' is overstating things a bit but it isn't terrible
battle cry either. Of course, one can apply XP paradigms to the writing
process as well...


|Though a nation watched her falling, yet a world could only cry |
|As they passed from us to Glory , riding fire in the sky.       |
|(Jordin Kare, Fire In The Sky)                                  |
|Farewell Columbia.                                              |
Tim Rowledge, tim at sumeru.stanford.edu, http://sumeru.stanford.edu/tim

More information about the Squeak-dev mailing list