Hannes,

I think you're missing the point of Stephane's message. He was pointing to
"code based" documentation which I interpret as a documentation of the
implementation rather than the architecture. Architectural issues (like how
things "should" be - notice the use of phrases like "typically" or "by
default" in the little blurb I wrote) cannot be covered by unit tests very
well. Similarly to "usage information" (e.g., how-to) since tests typically
have the wrong "usage density" (e.g., there should be tests for all the
#addMorph: variants none of which tells you that "the way to go" is to use
#addMorph: - tests actually can be confusing for this kind of information).
I'm sure Stephane is well aware of this.

Cheers,
  - Andreas

> -----Original Message-----
> From: squeak-dev-bounces at lists.squeakfoundation.org 
> [mailto:squeak-dev-bounces at lists.squeakfoundation.org] On 
> Behalf Of Hannes Hirzel
> Sent: Thursday, February 13, 2003 10:24 AM
> To: The general-purpose Squeak developers list
> Cc: The general-purpose Squeak developers list
> Subject: [DOCS] Re: Documentation [was: Morphic tutorial]
> 
> 
> 
> Hi Stephane
> 
> Stephane Ducasse <ducasse at iam.unibe.ch> wrote:
> > May be I should insist and say again that all effort of 
> documentation
> > (code based) out of the image are doomed and that Unit 
> tests are the 
> > only way to go.
> 
> Definitly no!
> 
> See Ralph Johnson's thoughts on documentation
> of June 1999 http://minnow.cc.gatech.edu/squeak/736
> 
> We need for example a good explanation about MorphicEvent handling
> as outlined by Andreas Raab in another thread.
> 
> Having a tutorial about using ProtoMorph for learning about Smalltalk
> reflection and learning about the Morph hierarchy is helpful as well.
> 
> 
> > Not sexy fancy supercool but the only way to get concrete scenario 
> > of the system
> > in a reproduceable way and in sync with the system because 
> even example 
> > methods got obsolete.
> 
> I agree that we need more unit tests as they provide an automatic
> mechanism
> to find out about inconsistences!
> 
> Regards
> Hannes
>