I've been cathching up on this discussion in the last few days and am boggled by the energy and enthusiasm that has developed. This is great news, as our documentation needs are quite large.
At the same time, I've been trying to figure out why this discussion causes me to feel unsettled. This post is very helpful; it has finally helped me figure out the cause. The approach outlined below is quite different from that which mozilla.org staff generally uses. That's not to say staff is right, or the approach below won't work, but it is not our standard operating style. In general, staff looks at existing contributors and people who have tried to contribute but run into problems, tries to identify what problems they are having and works to fix those problems. In the documentation world, this translates into encouraging people to create documentation, talking to those who are or who want to contribute documentation, finding out what problems they are having, and then developing whatever policies or tools are necessary solve existing problems. In other words, we would start out with a call for people to write, edit, maintain docs, and get to policy and tools later on. This way we avoid creating policies that aren't necessary, although at the price of needing a policy before we have one. This is of course the opposite approach to that outlined below. An example is the super-review requirement for code. This was instituted sometime around the fall of 2000, as I recall. Super-review is a pain, everyone agrees. Providing super-reviews is painful for the reviewers as well. Adding painful requirements to a volunteer project is a risky business, since it risks chasing people away. So we made sure we needed this requirement before we instituted it. We made sure by taking with our key contributors, discussing code quality, how to improve it, how to teach new engineers, etc. Eventually we decided on the super-review system. Not because we like it, but because we needed it and it was the best possible alternative to solve a known, important problem. Implementation of this policy required a large amount of effort, explaining to new participants, managers, etc. We were successful because experience showed that the problem of code quality could not be ignored and our key engineering contributors were convinced a policy was required. It will be interesting to see how this approach works. Staff is generally wary of creating policy before a crying need has been demonstrated, but perhaps we'll learn something new here. Mitchell Alexander J. Vincent wrote: > I'd like feedback on this text before I submit it to MozillaZine for > general viewing. Opinions and the occasional flame are invited. > > imajes has requested we mention PHP as a possibility; I think that's a > bit premature. > > <text> > Documentation efforts for mozilla.org are under the microscope right > now, and we need some help. We have two main foci: the policies for > documentation and developing tools for documentation. > > In the n.p.m.documentation newsgroup, there are several healthy debates > on policies for mozilla.org documentation going on, but we invite all > interested parties to deposit their two cents, so we can have a set of > policies worth their weight in gold. > > Regarding tools, we have a serious shortage of people willing to develop > them. Perl and/or possibly Python skills are particularly needed. (The > shortage is great enough where we're really unable to actually put new > ideas on the table.) > > As for the documentation itself... we are not yet ready in our opinion > to have an all-out push to organize, edit and write documentation on a > large scale. Nonetheless, we invite everyone to keep their eyes peeled > and to help out in any way they can. Even without the large push, I'm > sure a few of us would welcome some help with what we have now. > > Relevant links: > netscape.public.mozilla.documentation *** > http://www.mozilla.org/docs > http://www.mozilla.org/catalog > Bugzilla bug 151101 > Bugzilla bug 151952 > IRC channel #documentation > http://moz.zope.org > </text> >
