We don't seem to have a written document specifying requirements for review and/or super-review. This bug is to track the creation of a specific policy on what needs r=, what needs sr=, and who can give them. Assigning to Brian, who is more interested in defining this policy than I am.
Marking bug as blocking the documentation roadmap bug; we need a process linked to as an integral part of the roadmap. We should also review our roadmap under the proposed process ;)
I would like to see a module established for doc review in the code tree. Ian, would you consider owning this, and nominating some peers, please? Then, we can follow standard process for codetree docs, but for website stuff, we would have the caveat that review doesn't need to be so strict (ie, use common sense.) would that be inapropriate?
Created attachment 87892 [details] Tentative suggestions in re. r= and sr= for on-going documentation project Just some tentative suggestions as to how we might go about implementing r= and sr= procedures for the on-going documentation project. Comments welcome, particularly in n.p.m.d11n.
Created attachment 87896 [details] An HTML version of my previous attachment. WeirdAl asked if I could come up with a version of the previous attachement that was wasn't a mess, so I did a quick conversion to HTML. -- Sorry 'bout the mess on the previous one; I had no idea the text editor I'd been using would make such a mess of things.
Just discussing this in #documentation. Myself (David Gerard), Brian Heinrich and mpt are happy to apply our editorial experience to the role of r=/sr= for doc, and WeirdAl for sr= (proofreading). (It'll be no prob for me within any anticipated time constrictions.) Does this sound workable to you all?
Oh, and James Cox (imajes) as r=/sr= patsy too.
Just got wind of this. I'm in and out of the mozilla project, but I can usually find time to do reviews, add me onto the reviewer's list. Use my email@example.com account, please.
Speaking for myself only (not mozilla or netscape), I'm a bit ambivalent about this idea, especially for "developer docs". Our biggest problem in the doc tree, by a long shot, is information that's either not there or outdated. I don't know that I've ever heard any complaints about information that was incorrect at the time it was posted. This seems to be an attempt to solve that last problem, at the cost of making checking in documents to the tree require more effort. Given that it's already fairly difficult to motivate the people who know about the code (especially developers) to write enough documentation, this seems like a step in the wrong direction. The r= for content might be a good recommendation, but I don't know that it should be required. And I feel that sr= imposes more cost than it provides benefit.
Personally, I dislike this idea. Today, I worked from 2:00 to now blitzing across open documentation bugs, and checking in any quick changes I can make. Many of these are one-line changes - a typo here, a messed up bug number there - so I just check in the fix r=malachi. Requiring me to get seperate r and sr for this would mean waiting *even longer* to fix bugs open since 2001. And that seems like a bad idea to me.
In re. comment #9: The idea was -- and I guess still is -- simply to try to ensure that documentation is accurate and appropriate; r= and sr= was/is intended primarily for new documentation and substantial revisions to existing documentation. In fact, using r= and sr= (where sr= is largely an upper-level editorial/sanity-checking function) was to help prevent against the kind of situation you're describing. Further, in cases such as the one you're describing, the change would go in as you've described but the doc's 'owner' would be apprised of the change. Don't know if that clarifies anything. . . .
I do see the reasoning behind this. And I do appraise the owner before I check in, of course. AAH! I just read over the description again! So, for my one lines, check in r=malachi, tell the owner. For a big change, get a document R+SR, then check in. I guess I have to retract my previous statement -- this seems like a great idea =) I would propose, however, that it wait until we have more writing support. I agree with dmose -- _right now_, this seems like a bad thing to toss upon the programmers. When we get more steady outside maintenance of documentation, we should definately implement this. The only thing that can come of it is better document writing. I would also like to toss my hat in to serve as a reviewer. I can r or sr... tell me what we would need if/when the time comes. Thanks, by the way -- that really did clear things up =)
What Dan Mosedale said, plus note that checking in bad docs isn't as bad as checking in bad code, since it doesn't immediately break the application and idle engineers. Rather than instituting more review, we'd be better off with less; in particular, spelling and grammatical changes shouldn't require document owner approval (which wastes everybody's time) so people can correct minor mistakes that get checked in.
I propose adopting the devmo review requirements: http://developer-test.mozilla.org/contribute/review
1+ vote from me on fantasai's suggestion. Two questions: 1. who own what document? 2. what about commual/user documentation?
For documents without a contributor listed, check Bonsai to see who's been most active in the last 10 updates or so and ask them: if they're the wrong person, chances are they can redirect you to the right person. If it's a high-profile page, email website-drivers.