Ian, thanks. Comments inline.<br><br><div class="gmail_quote">On Fri, Apr 30, 2010 at 1:36 PM, Ian Trudel <span dir="ltr"><<a href="mailto:ian.trudel@gmail.com">ian.trudel@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
2010/4/30 Casey Ransberger <<a href="mailto:casey.obrien.r@gmail.com">casey.obrien.r@gmail.com</a>>:<br>
<div class="im">> One thing I didn't do, that I probably should have done, is to explicitly<br>
> list what I think our priorities should be regarding documentation. As much<br>
> as it pains me that we don't have a spell checker, for example, I'd put that<br>
> waaay behind a cleanup effort for class comments; I'd put *all* tool work<br>
> behind that.<br>
<br>
</div>I completely disagree on this one. I would concede that editing and<br>
formatting tools may not be as high priority as a spell checker.<br>
However, a spell checker should be mandatory. Many in our community<br>
are non-native English speakers.<br>
<br>
Let's imagine there is a documentation frenzy without a spell checker.<br>
People contribute like crazy and we are on a roll. Great you say.<br>
Great it is. Then we realize that we have more documentation but with<br>
poor quality, it's hardly readable. We will be forced to rework all<br>
texts. It sounds like documenting twice the same system! :O<br>
<div class="im"><br></div></blockquote><div><br></div><div>Somehow I doubt we'll have a documentation-frenzy. That would be a momentous day in software history, and a great problem to have.</div><div><br></div><div>Okay, I would love to have a spell checker in Squeak. It would need to be:</div>
<div><br></div><div> - Easy to install. I'm thinking, MC package. Requiring a VM primitive would set the barrier for contribution too high IMHO. </div><div> - It should be easily unloadable (many of us probably have no use for a spell checker in our images.)</div>
<div><br></div><div>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</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">
> So here's my top three priorities (you may of course disagree:)<br>
> 1. Get a process running around using HelpSystem.<br>
<br>
</div>I believe in the HelpSystem. It needs some tweaking but it's a good<br>
system to begin with. A mechanism for content contribution and<br>
distribution, as you called it, should be put in place quickly. Trunk<br>
style. Perhaps even integrated to the trunk. It has to be available<br>
everywhere to ensure a good stream of contributions.<br>
<div class="im"><br></div></blockquote><div><br></div><div>Agreed. I just sent another message about this. </div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">
> 2. A useful, current comment for every class.<br>
<br>
</div>This could be a good start. One of the thing that should be higher in<br>
priority than #3 is usage examples. It is sometimes time consuming to<br>
figure out how to properly use some classes.<br>
<div class="im"><br></div></blockquote><div><br></div><div>I think examples raise the quality of class comments. Absolutely.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">
> 3. Consider first method comments which show up in tools that can extract<br>
> them.<br>
<br>
</div>Another suggestion: we should have something to tell us how much<br>
documentation coverage we have. This set an objective to our<br>
community: having 100% coverage.<br>
<div><div></div><div class="h5"><br></div></div></blockquote><div><br></div><div>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. </div>
<div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div><div class="h5">
Ian.<br>
--<br>
<a href="http://mecenia.blogspot.com/" target="_blank">http://mecenia.blogspot.com/</a><br>
<br>
</div></div></blockquote></div><br>Thanks for your feedback!<br clear="all"><br>-- <br>Casey Ransberger<br>