[squeak-dev] Proposal: Project Pink Book

Ian Trudel ian.trudel at gmail.com
Fri Apr 30 20:36:43 UTC 2010


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

> 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.

> 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.

> 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.

Ian.
-- 
http://mecenia.blogspot.com/



More information about the Squeak-dev mailing list