[DOCS] Project "Magic Book"

Ivan Tomek ivan.tomek at acadiau.ca
Tue Feb 11 00:07:56 UTC 2003

Yes. I think my point was that it is good to have an idea of what one wants
to do and perhaps even write it down in an organized way, but it's probably
going to change a lot as the project evolves and the manual may then share
the usual fate of documentation - fall behind, never catch up, describe
something else than the real thing.


> -----Original Message-----
> From: Tim Rowledge [mailto:tim at sumeru.stanford.edu]
> Sent: Monday, February 10, 2003 8:05 PM
> To: squeak-dev at lists.squeakfoundation.org
> Subject: RE: [DOCS] Project "Magic Book"
> 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...
> tim
> -- 
> +================================================================+
> |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