making review/bug filing optional for some docs changes

[Myk Melez]

Dave,

I suggest we make review and bug filing optional for some docs changes 
made by a group of trusted docs writers.  Although waiving these steps 
means more bugs, it also means more docs improvements, and I think the 
benefits outweigh the costs for a set of docs writers with known good 
skills.  Instead of rehashing all the arguments, please find below most 
of the IRC discussion on the subject.

-myk


myk 	i can never remember; does docs hacking require review?

	Tru <irc://irc.mozilla.org/tru,isnick> 	Yes

	LpSolit <irc://irc.mozilla.org/lpsolit,isnick> 	myk, yes, review 
requested but approval is not

	myk 	hmm, i thought there were some laxer review requirements for docs

	LpSolit <irc://irc.mozilla.org/lpsolit,isnick> 	Tru, yes

	travis <irc://irc.mozilla.org/travis,isnick> 	[11:51] <myk> hmm, i 
thought there were some laxer review requirements for docs <== It *is* 
more lax. The intent is to ensure that things are syntactically and 
grammatically correct, and that they are not missing any obvious 
information ... not that they are 100% complete and accurate in all things.

	travis <irc://irc.mozilla.org/travis,isnick> 	Basically, anything is 
better than nothing as far as documentation goes. The review is to 
ensure that we follow proper English grammar and structure, and that 
things are organized at least reasonably well. It is also a second pair 
of eyes and a second head full of knowledge, which might find 
cross-connections of which the original author was unawares... and it's 
easier to fix these things before checkin than after.

	You don't request a documentation review of a specific person, though; 
you request it of the component owner. People who can do reviews are 
watching that owner, and that queue.

	(the component owner is documentation at bugzilla.bugs 
<mailto:documentation at bugzilla.bugs> -- a fake account set up just for 
this purpose.)

	travis <irc://irc.mozilla.org/travis,isnick> 	Yes, the Developer Docs 
need an update on this procedure; that's one of the developments in the 
queue. :)

	Tru <irc://irc.mozilla.org/tru,isnick> 	nods.

	Travis - is there a bug up for that?

	myk 	travis: it may be easier to fix code issues before checkin, but 
docs issues would be just as fixable after checkin as before if review 
were not required

	travis <irc://irc.mozilla.org/travis,isnick> 	LpSolit: documentation 
bugs do not require approval

	just review

	once they have been reviewed, they can be checked in to the tree.

	Tru <irc://irc.mozilla.org/tru,isnick> 	Myk - I think that requiring 
review is appropriate.

	Tru <irc://irc.mozilla.org/tru,isnick> 	Myk - the reason being - if we 
dump poor documentation on our users, it's going to very negatively 
impact their view of the software.

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: you're probably 
right, and back in the days where only Jake was doing documentation 
work, he wouldn't bother asking for anyone for review because there was 
nobody toa sk

	to ask*

	myk 	Tru: perhaps it would make sense to designate a group of Bugzilla 
hackers whose linguistic skills we trust and not require review for that 
group

	f.e. the set of docs reviewers

	Jake <irc://irc.mozilla.org/jake,isnick> 	And when Jake came back to it 
in Iraq he was still in the habit of not requesting review and that had 
a tendency to annoy travis :)

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: I'd like to think 
that I'm in that group (of those whose linguistic skills can be 
trusted), and I approve of having someone else look over my patches 
before they go in.

	I don't know everything by any means, and often there have been 
technical corrections that made the whole thing better.

	Jake <irc://irc.mozilla.org/jake,isnick> 	Docs review is a lot like 
proof reading before you turn in your English paper

	myk 	travis: that's ok; i'm not suggesting that you can't get review or 
that it's never useful

	travis <irc://irc.mozilla.org/travis,isnick> 	nods at Jake.

	Tru <irc://irc.mozilla.org/tru,isnick> 	While I may want to consider 
myself part of that group, I would rather not have that responsibility 
on my shoulders. If I make a mistake and I update, then I don't get to 
share the blame. If I make a mistake and a reviewer misses it too, then 
we both get to share blame.

	travis <irc://irc.mozilla.org/travis,isnick> 	In fact, it's like having 
someone *else* proofread your English paper, which is the best way to do 
it.

	Tru <irc://irc.mozilla.org/tru,isnick> 	nods at travis and jake.

	myk 	travis: i'm just suggesting that it would be beneficial to not 
require review in some cases

	Tru: i'm part of that group, and i do want that responsibility

	Tru <irc://irc.mozilla.org/tru,isnick> 	So - if nobody reviews your 
update but the update (unintentionally) leads users astray, who will 
know about it besides you?

	myk 	i don't care about blame, i care about improving docs; and i have 
good english skills, but i don't have a lot of time; going through 
thebug->review->checkin cycle for fixes like the one i just made to 
using.xml is way too much work for a change of that magnitude

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: we had an email 
discussion like this about six months ago -- Vlad, Jake, Dave and I -- 
which is when this current policy was formed. I'm not averse to 
reopening the discussion for the purposes of very small fixes -- on the 
order of what you were doing today -- but IMHO anything larger than that 
*needs* a second pair of eyes.

	myk 	Tru: everyone, the moment someone reports the error

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: Would you still be 
willing to make a bug and a patch? Or are you looking at just hacking 
the docs directly with no public record?

	myk 	travis: i'm suggesting hacking the docs directly with the CVS 
public record

	travis <irc://irc.mozilla.org/travis,isnick> 	(I'm wondering if you're 
just trying to skip the review phase, or the whole bug creation/patch 
creation/patch uploading/bug closing phase)

	myk 	travis: i'm suggesting that a group of hackers be able to skip all 
those phases for a set of changes

	Tru <irc://irc.mozilla.org/tru,isnick> 	Myk - I guess where I'm coming 
from - I depend heavily on the docs being accurate. If they're not or 
they mislead, then I wind up wasting my time as a user. If a lot of 
users are doing the same thing, then how much time is wasted? Is it more 
wasted time to utilize the process or more wasted time for users to be 
lead astray?

	myk 	travis: obviously there are some changes large enough to require 
review, but i think the hackers we trust to make changes without review 
can also be trusted to decide when it's necessary

	Tru: i think it's more wasted time for the users, because busy hackers 
like me aren't going to update the docs nearly as much if we have to go 
through a more cumbersome process to do so

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: by the same token, 
are you not a Trusted Code Hacker? By that same logic, should we not 
just say, "Myk knows what he's doing as far as the UI goes, and he can 
just hack the UI code with only the CVS as public record?" If not -- and 
this is an honest question, not sarcasm -- what do you perceive as the 
difference between the two?

	myk 	travis: code bugs break the app for other hackers, who have to 
stop working until the bustage gets fixed; errors in documentation do 
not generally stop docs hackers from working on them

	travis: so code bugs are more serious

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: If the review adds more 
time to getting the documentation update into CVS, how does that prevent 
you from continuing what you're doing?

	myk 	Tru: it's the whole process that takes more time

	myk 	travis: but as a matter of fact i do think that we could 
beneficially waive the review requirement for some kinds of hacking

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: What's preventing you from 
making updates to your Bugzilla installation and following the process 
for the rest of us?

	travis <irc://irc.mozilla.org/travis,isnick> 	Tru: ethics

	myk 	Tru: i don't have a Bugzilla installation; i'm hacking on Bugzilla

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: That's a problem from my 
perspective because those of us who do can be negatively impacted from 
an error in an update regardless of the size.

	myk 	Tru: i don't understand; what's a problem from your perspective?

	Tru <irc://irc.mozilla.org/tru,isnick> 	It's also one reason why I'm 
writing a Pre-Release Testing Guide to cover all of Bugzilla.

	The problem from my perspective is not following the process to prevent 
human error.

	myk 	Tru: sure, not requiring review will sometimes result in errors 
with negative impact to others

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: I do understand 
where you're coming from. Having to follow any procedure is always a 
PITA, and slows things down. I would be willing to entertain discussion 
about 'trusted docs hackers' not needing a review, but relying 
completely on CVS for tracking is not something I'm personally 
comfortable with.

	Tru <irc://irc.mozilla.org/tru,isnick> 	How many times have each of us 
made mistakes on even little things that caused problems? I'd raise my 
hand more times than I can count. It's not that we can't make changes 
without making mistakes, it's that we do make mistakes and sometimes we 
don't catch them till they're a problem.

	myk 	Tru: not requiring two reviews, which is what we do now, also has 
that problem

	myk 	Tru: in fact, i just reviewed and checked in some docs code today 
only to find i missed a problem

	Tru: but we don't require two reviews because the benefit in reduced 
errors isn't worth the effort

	Tru: my suggestion is that not requiring one review gives us more 
benefit than it costs us in some cases

	Tru <irc://irc.mozilla.org/tru,isnick> 	See? That's the whole point I 
was trying to make - even reviewers make mistakes, but at least the 
reviewer (you) looked at it and had an opportunity to catch a problem.

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: it's a matter of 
perspective. I hear you saying that even one review on docs isn't 'worth 
the effort'. I recognize that you feel that way, but I don't feel the 
same way.

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: having been a production 
operations manager, I completely agree with travis that not reviewing 
under 'certain' circumstances leads to a greater potential for problems 
and abuse of process that was put in place to protect us from ourselves. 
Process does add time initially but if it saves us from releasing buggy 
updates, then it saves us time and reputation.

	myk 	travis: sure, i understand. i would just suggest that it's 
probably because we're different, and different processes would be 
optimal for us, and we should be more flexible in applying processes to 
different hackers to make the best use of their capabilities and potential

	myk 	Tru: sure it does, but it also has greater potential for solutions 
and better docs

	LpSolit <irc://irc.mozilla.org/lpsolit,isnick> 	travis, could you check 
this patch in?

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: Maybe we should just agree 
to disagree on this. Please don't get me wrong - I'm not picking on you. 
I have two responsibilities in my job - writing Bugzilla code and 
administering an active Bugzilla. As an administrator, I want to be sure 
I'm only using well-tested code.

	myk 	Tru: i think the additional problems from not reviewing some docs 
would be compensated for many times over by the additional docs and doc 
improvements such a policy would open the door for

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: If you don't want to wait 
for review, that's fine with me. File your bug and patch, then feel free 
to move on. :)

	myk 	Tru: i can't do that at the moment, since that would be breaking 
the rules

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: that way also lies 
resentment, however. Based on discussion on the developers@ list, I 
would bet that Gerv would think that he deserves Trusted Docs Hacker 
status. Based on the response to his suggestions, others do not.

	myk: *file* the bug and move on, not *fix* the bug.

	myk 	Tru: but i'd like more than that anyway; i want to not have to 
file bugs on some fixes

	Tru <irc://irc.mozilla.org/tru,isnick> 	I don't think anyone deserves 
that status because we're all human.

	myk 	Tru: it works pretty well in the Mozilla community

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: I know nothing about 
the Mozilla community, so I can't comment. Are you talking docs only, or 
everything?

	myk 	travis: perhaps; but we can't not make decisions because some 
people will resent them; it's our responsibility as project managers to 
make the hard decisions about who gets such privileges and others (like 
to become a reviewer)

	myk 	travis: i'm talking docs mostly, where bugs don't need to be filed 
and/or changes don't need review in a number of cases; but there are 
also some places where review is waived for code as well, and i believe 
bugs don't need to be filed for some really minor code fixes

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk: As I see it, that's a 
really slippery slope. If we give approval for certain kinds of updates, 
what's to prevent someone from abusing that power to make updates beyond 
the scope of the authorization?

	travis <irc://irc.mozilla.org/travis,isnick> 	myk: okay, well, you're 
definitely talking about a change to How Things Are Done At Bugzilla... 
so it's worth bringing up on the developers@ list if you feel strongly 
about it... or maybe, better yet, use reviewers@ (now that it's a 
discussion list). I'm fairly confident that you'll receive some support 
from some corners, based on past posting history, and the discussion 
itself is probably worth having.

	I doubt anything is going to be settled in IRC, though. Just my feeling.

	myk 	Tru: the same things preventing them from doing it now, given that 
most Bugzilla privileges aren't restricted programmatically: tight 
feedback loops

	myk 	travis: ok, i'll do so

	Tru <irc://irc.mozilla.org/tru,isnick> 	myk - I think you are one of 
the people that if we were going to do something like that for, I would 
be in favor of you having that capability. The problem is, I'm not 
against you having the ability, I'm against the entire concept of making 
updates to Bugzilla that aren't in the DB for someone to search on. I 
also feel that having a reviewer review means that someone else can act 
as a check/balance to make sure the update is taking Bugzilla in the

travis <irc://irc.mozilla.org/travis,isnick> 	"I'm not against you 
having the ability, I'm against the entire concept of making updates to 
Bugzilla that aren't in the DB for someone to search on." <-- this says 
it well for me also.

	myk 	travis, Tru: but they are in the db; they're in CVS and in bonsai

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bugzilla.org/pipermail/developers/attachments/20050317/83c1ffae/attachment.html>