Documentation needs a written review/super-review document



Developer Documentation
15 years ago
5 years ago


(Reporter: WeirdAl, Assigned: Dawn Endico)




(2 attachments)



15 years ago
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.

Comment 1

15 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

Comment 2

15 years ago
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

15 years ago
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.

Comment 4

15 years ago
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.

Comment 5

15 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

15 years ago
Oh, and James Cox (imajes) as r=/sr= patsy too.

Comment 7

15 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 account, please.

Comment 8

15 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

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.

Comment 10

15 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. . . .
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.

Comment 13

13 years ago
Assignee: bah_pop3 → endico

Comment 14

13 years ago
I propose adopting the devmo review requirements:

Comment 15

13 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

13 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.


12 years ago
Last Resolved: 12 years ago
Resolution: --- → WONTFIX
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
Component: Documentation Requests → Documentation
Product: Mozilla Developer Network → Mozilla Developer Network
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.