152208 - Documentation needs a written review/super-review document

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: General, defect)

Description

[Alex Vincent [:WeirdAl]]

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

[Alex Vincent [:WeirdAl]]

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 ;)

Comment 2

[James Cox]

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

[Brian Heinrich]

Attachment: 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

[Brian Heinrich]

Attachment: 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

[David Gerard]

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

[David Gerard]

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

Comment 7

[Karl Guertin]

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
[e-mail] account, please.

Comment 8

[Dan Mosedale (:dmosedale, :dmose)]

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

[Owen Marshall (Not reading bugmail)]

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

[Brian Heinrich]

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

[Owen Marshall (Not reading bugmail)]

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

[Myk Melez [:myk] [@mykmelez]]

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

[Anne (:annevk)]

.

Comment 14

[fantasai]

I propose adopting the devmo review requirements:
  http://developer-test.mozilla.org/contribute/review

Comment 15

[Daniel Wang]

1+ vote from me on fantasai's suggestion.
Two questions: 1. who own what document? 2. what about commual/user documentation?

Comment 16

[fantasai]

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.