2010/4/30 Casey Ransberger casey.obrien.r@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:)
- 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.
- 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.
- 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.