[squeak-dev] Proposal: Project Pink Book

Casey Ransberger casey.obrien.r at gmail.com
Fri Apr 30 21:19:29 UTC 2010


Ian, thanks. Comments inline.

On Fri, Apr 30, 2010 at 1:36 PM, Ian Trudel <ian.trudel at gmail.com> wrote:

> 2010/4/30 Casey Ransberger <casey.obrien.r at gmail.com>:
> > One thing I didn't do, that I probably should have done, is to explicitly
> > list what I think our priorities should be regarding documentation. As
> much
> > as it pains me that we don't have a spell checker, for example, I'd put
> that
> > waaay behind a cleanup effort for class comments; I'd put *all* tool work
> > behind that.
>
> I completely disagree on this one. I would concede that editing and
> formatting tools may not be as high priority as a spell checker.
> However, a spell checker should be mandatory. Many in our community
> are non-native English speakers.
>
> Let's imagine there is a documentation frenzy without a spell checker.
> People contribute like crazy and we are on a roll. Great you say.
> Great it is. Then we realize that we have more documentation but with
> poor quality, it's hardly readable. We will be forced to rework all
> texts. It sounds like documenting twice the same system! :O
>
>
Somehow I doubt we'll have a documentation-frenzy. That would be a momentous
day in software history, and a great problem to have.

Okay, I would love to have a spell checker in Squeak. It would need to be:

 - Easy to install. I'm thinking, MC package. Requiring a VM primitive would
set the barrier for contribution too high IMHO.
 - It should be easily unloadable (many of us probably have no use for a
spell checker in our images.)

I don't know of a spell checker implementation for Squeak. Is there one out
there? If not, can you implement one and then get back to me right away? :P

> So here's my top three priorities (you may of course disagree:)
> > 1. Get a process running around using HelpSystem.
>
> I believe in the HelpSystem. It needs some tweaking but it's a good
> system to begin with. A mechanism for content contribution and
> distribution, as you called it, should be put in place quickly. Trunk
> style. Perhaps even integrated to the trunk. It has to be available
> everywhere to ensure a good stream of contributions.
>
>
Agreed. I just sent another message about this.

> 2. A useful, current comment for every class.
>
> This could be a good start. One of the thing that should be higher in
> priority than #3 is usage examples. It is sometimes time consuming to
> figure out how to properly use some classes.
>
>
I think examples raise the quality of class comments. Absolutely.


> > 3. Consider first method comments which show up in tools that can extract
> > them.
>
> Another suggestion: we should have something to tell us how much
> documentation coverage we have. This set an objective to our
> community: having 100% coverage.
>
>
This is actually something that I thought about doing. I'd call it a strong
nice-to-have. This one seems like it wouldn't be that hard to pull off,
either.

Coverage is kind of a funny metric though. 100% coverage is great to have,
but doesn't tell you anything about the quality of your coverage.


> Ian.
> --
> http://mecenia.blogspot.com/
>
>
Thanks for your feedback!

-- 
Casey Ransberger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100430/893a63c9/attachment.htm


More information about the Squeak-dev mailing list