making review/bug filing optional for some docs changes

[Gervase Markham]

Shane H. W. Travis wrote:
  > When Gerv brought up this topic before, he named about six things that
> needed doing on the documentation that could only be done in 'grand,
> sweeping changes', and that all he needed was a completely free hand and 12
> solid hours of hacking to bring the documentation up to snuff. I disagreed
> with him on whether or not the process was broken, and asked him to file
> documentation bugs on any or all of the things he said that needed changing,
> as they all sounded valid. I welcomed his contributions, and invited his
> contribution on those issues, or any promised to make the review procedure
> as quick and painless as possible.
> 
> To date, to the best of my knowledge, nothing has been done on that front;
> No bugs filed, no patches uploaded, nothing.

Nope. And, thinking about it, here's why. Doing the analysis to find out 
what needs fixing, and writing up some sort of proposal to explain it in 
detail, is simply an impossible task.

Last time I did a big docs whackage, I spent 16 hours over two days 
cutting, pasting, moving, rereading, refining, eliminating - *editing*. 
I had no idea when I started about exactly what I'd be touching and 
where I'd end up, and couldn't have explained it - it was just fairly 
obvious that the docs were in various areas poorly organised, 
repetitive, unclear and redundant and they needed work.

Here, as an example, is the diffs of the changes I made, just to the 
installation section. There is hardly a single line left untouched.
http://bonsai.mozilla.org/cvsview2.cgi?diff_mode=context&whitespace_mode=show&file=installation.xml&branch=&root=/cvsroot&subdir=mozilla/webtools/bugzilla/docs/xml&command=DIFF_FRAMESET&rev1=1.58&rev2=1.59

Here the page is before:
http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/webtools/bugzilla/docs/xml/installation.xml&rev=1.58
And here it is after:
http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/webtools/bugzilla/docs/xml/installation.xml&rev=1.59

Now, that section was, as a whole, absolutely definitely much, much 
better after I'd finished than before I started (if you disagree with 
that, shout - but I really don't expect anyone to). But before I 
started, could I have defined what I was going to do? Not except in 
terms so vague as to be useless.

Once I'd finished, a couple of bugs got filed - "you changed this, and 
we don't like it". Cool - no problem. Let's change it back. That doesn't 
mean the entire procedure was broken, just as if you check in a code 
patch and it causes regressions, it doesn't mean the patch was a bad idea.

Now, I'm not expecting to be allowed to do such a major change the day 
before a release. Which is why I suggested that such changes should be 
allowed while the tree is not frozen. Then, during the freeze period, we 
can read and review the documentation - which hopefully, is structurally 
sound by this point - and fix factual errors.

> Were someone to try and take such an attitude to the codebase, the answer
> would be, "Sorry to hear that; there's the door.  Don't let it hit you in
> the ass on the way out." Documentation is perceived as 'lesser', though,
> because one cannot 'break' it in the same way that one can break code; no
> amount of poor English, typographical errors, or factual inaccuracies will
> stop it from being The Documentation.

Documentation is not perceived as "lesser" - at least, not by me - it's 
perceived as _different_. Because you can't break it, and because people 
like working on it less, the procedure for achieving the highest quality 
documentation with the resources available is different from the 
procedure for achieving the highest-quality code.

Gerv