[ANN] Cash For Documentation project

Thu Sep 5 08:04:04 UTC 2002

Hi all!

Jack Keel <jhkeel at facstaff.wisc.edu> wrote:
> To the harvesters (or anyone who actually controls the content of Squeak),
>
> What is the best way to get a large number of class comment changes approved?

I would say the best way is to go the ordinary route by posting a FIX
with a preamble explaining that this fix contains nothing but good class
comments (no code changes). :-)

Such a FIX would be very easy for a harvester to just read through and
let in. Especially if its class comments for uncommented classes (since
such a comment by definition is better than none, at least as long as it
doesn't contain obvious errors).

> http://sqdb.squeak.info seems to be a nice attempt but there are no 
> changes after the initial flurry of interest and it is not clear that 
> any changes here will actually end up in Squeak anyway. 
> 
> http://www.squeakdoc.org seems to have had very little activity. Also 
> it is not obvious that anything added to this site will actually make 
> it into Squeak.

Both of those projects are admirable. But personally I think that
systems "external" to the Squeak image will have a hard time getting
full attention. It is the same thing with SqueakMap (though it is still
just in beta) and that is why I am now putting my effort into building a
nice morphic browser for it.

> Cash for Documentation (http://minnow.cc.gatech.edu/squeak/2653) 
> seems to be lifeless.  More $ interest in enhancements than in 
> documentation.  And it has no procedures or directions for actually 
> making the changes - even if you wanted to do them for free.
> 
> Are there comment guidelines somewhere?  The present comments look 

Surely there are but there are many different styles. IMHO I think that
is fine. There is no universal recipe for making good class comments.
And since we are in such a desperate need for class comments we would
gratefully accept whatever is produced, as long as it isn't "rubbish".
:-)

And different styles are suitable for different classes - for example,
highly technical classes intended as components should probably (among
other things of course) describe their instance variables in some detail
and explain the most important protocols. But tool classes should
instead focus on what the tool does and how to use it. This is just a
reflection on the most common exposure for the class: Is it primarily
just used (tools etc) or is it a component primarily used in
programming?

Another example is abstract classes (intended as superclasses) which
should IMHO place some real effort in explaining what an instance of the
class *is*. 95% (a number out of thin air) of all inheritance is based
on the "IS A" relation so this is very important to understand.

> awful in Dandelion because it must do a <pre> around them to maintain 
> any formatting that does exist which results in very, very long 
> lines.  Is Dandelion even accepted as a good way to browse (i.e., 
> would comments formatted for Dandelion be accepted by the Squeak 
> Browser lovers?).

I think that the class comments primarily should "work" in the browsers,
and I also think we should keep them simply formatted.

Dandelion could start by limiting the lines to 80 characters and then do
a <pre> around that.

> Jack
> 
> 
> 
> 
> 
> -- 
> 
> --Boundary_(ID_Zzom4wIvmDX8u5mxIDjX+w)
> Content-type: text/html; charset=us-ascii
> Content-transfer-encoding: 7BIT
> 
> <!doctype html public "-//W3C//DTD W3 HTML//EN">
> <html><head><style type="text/css"><!--
> blockquote, dl, ul, ol, li { padding-top: 0 ; padding-bottom: 0 }
>  --></style><title>Re: [ANN] Cash For Documentation
> project</title></head><body>
> <div>To the harvesters (or anyone who actually controls the content of
> Squeak),</div>
> <div><br></div>
> <div>What is the best way to get a large number of class comment
> changes approved?</div>
> <div><br></div>
> <div><font color="#551A8B"><u>http://sqdb.squeak.info</u></font><font
> color="#000000"> seems to be a nice attempt but there are no changes
> after the initial flurry of interest and it is not clear that any
> changes here will actually end up in Squeak anyway.&nbsp;</font></div>
> <div><br></div>
> <div><font
> color="#551A8B"><u>http://www.squeakdoc.org</u></font><font
> color="#000000"> seems to have had very little activity</font>. Also
> it is not obvious that anything added to this site will actually make
> it into Squeak.</div>
> <div><br></div>
> <div>Cash for Documentation (http://minnow.cc.gatech.edu/squeak/2653)
> seems to be lifeless.&nbsp; More $ interest in enhancements than in
> documentation.&nbsp; And it has no procedures or directions for
> actually making the changes - even if you wanted to do them for
> free.</div>
> <div><br></div>
> <div>Are there comment guidelines somewhere?&nbsp; The present
> comments look awful in Dandelion because it must do a &lt;pre&gt;
> around them to maintain any formatting that does exist which results
> in very, very long lines.&nbsp; Is Dandelion even accepted as a good
> way to browse (i.e., would comments formatted for Dandelion be
> accepted by the Squeak Browser lovers?).</div>
> <div><br></div>
> <div>Jack</div>
> <div><br></div>
> <div><br></div>
> <div><br></div>
> <div><br></div>
> <div><br></div>
> <x-sigsep><pre>-- 
> </pre></x-sigsep>
> </body>
> </html>
> 
> --Boundary_(ID_Zzom4wIvmDX8u5mxIDjX+w)--