[squeak-dev] Proposal: Project Pink Book
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
> > as it pains me that we don't have a spell checker, for example, I'd put
> > 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,
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.
Thanks for your feedback!
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Squeak-dev