Closed
Bug 152208
Opened 22 years ago
Closed 19 years ago
Documentation needs a written review/super-review document
Categories
(Developer Documentation Graveyard :: General, defect)
Developer Documentation Graveyard
General
Tracking
(Not tracked)
RESOLVED
WONTFIX
People
(Reporter: WeirdAl, Assigned: endico)
References
Details
Attachments
(2 files)
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.
Reporter | ||
Comment 1•22 years ago
|
||
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 ;)
Blocks: 151101
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?
Comment 3•22 years ago
|
||
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.
Comment 4•22 years ago
|
||
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.
Comment 5•22 years ago
|
||
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?
Comment 6•22 years ago
|
||
Oh, and James Cox (imajes) as r=/sr= patsy too.
Comment 7•22 years ago
|
||
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 grayrest@grayrest.com account, please.
Comment 8•22 years ago
|
||
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.
Comment 9•22 years ago
|
||
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.
Comment 10•22 years ago
|
||
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. . . .
Comment 11•22 years ago
|
||
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 =)
Comment 12•22 years ago
|
||
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.
Comment 14•20 years ago
|
||
I propose adopting the devmo review requirements: http://developer-test.mozilla.org/contribute/review
Comment 15•20 years ago
|
||
1+ vote from me on fantasai's suggestion. Two questions: 1. who own what document? 2. what about commual/user documentation?
Comment 16•20 years ago
|
||
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.
Reporter | ||
Updated•19 years ago
|
Status: NEW → RESOLVED
Closed: 19 years ago
Resolution: --- → WONTFIX
Updated•17 years ago
|
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
Updated•12 years ago
|
Component: Documentation Requests → Documentation
Updated•12 years ago
|
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation
You need to log in
before you can comment on or make changes to this bug.
Description
•