> -----Original Message-----
> From: MIME :eluwish at uswest.com > Sent: Tuesday, June 08, 1999 2:15 PM
> To: squeak at cs.uiuc.edu
> Subject: Re: Documentation
> > > I like stp's approach, since it removes the "clutter" of long > stretches of source
> code - if the documentation is really good, you shouldn't > have to read the source to
> figure out what something does and how to make it do it.  I > would add the following:

This might be true, except that "documentation" does not equate to "comments" for well-written Smalltalk code.  Smalltalk was designed to be read in a browser, and accordingly, the use of "comment-style" documentation is far sparser than for regular code, and the comments themselves don't always make a great deal of sense outside the context of the source code itself.  Reading the writings of those acknowledged by others to be "great" Smalltalk coders, proper Smalltalk code by its nature is largely self-documenting.  If the code gets obscure, it is usually an indication that refactoring is necessary.

Accordingly, I'm not sure it's consistent to say, at least for well-written Smalltalk, that "if the documentation is really good, you shouldn't have to read the source to figure out what something does."

> 1) Method documentation should include the method comments, > the class of the
> arguments for keyword messages, and the class of the object > it returns (if not of
> the same class as the receiver)

This isn't meaningful for Smalltalk methods.  

There is no way to know the class of the arguments or the class of the object returned, except on a message-send-by-message-send basis.  This latter property of late-binding message sends is one of the defining properties of the language.

> I know that it's easier to add two cents rather than actually > do the work...
> I'm just throwing out some ideas based loosely on how I > learned what I know about
> Smalltalk, mostly without the kind of documentation I wish I > had.  Perhaps we should
> collect these experiences we all have had - if we get some > sense of how people learn
> this complex system, perhaps we can do something constructive > to help others along.

I know how difficult this will be to hear -- I had problems with it at first as well.  But the documentation really *is* the code.  When I first downloaded Squeak, I noticed that the printOut method didn't work properly.  Stunned, thinking that would be one of the first targets for a fix in a development system, I found the (subtle) bug, submitted my fix, and asked Ted how he got along without it.  I was amazed at his answer -- he doesn't use printouts.  I asked twice.

This is not to say that Squeak is well-documented presently.  There is a Smalltalk style of documentation, and the present image is fairly incomplete even by that standard.  But what would constitute a completed document may be substantially different than what you are presently envisioning.

All I am really saying is this: try coding the Squeak way for awhile before judging how documentation "should" be written.  Read what people who have been building Smalltalk systems for awhile say about coding style.  And read some source code until you are fluent in the language and it idioms.  Do all of these things, and then re-think what (if any) written documentation you require.

I understand your thinking -- I really do.  The software engineering principles are the same regarding documentation, but the implementation *is* different.  You must understand that in Smalltalk, the code is and can be documentation as well, and moreso, than the comments.