making review/bug filing optional for some docs changes

[Benton, Kevin]

> Shane H. W. Travis wrote:
> > 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.

I don't see it as being an impossible task.  I also don't think it needs
to be highly detailed.  I think it should be detailed enough for a
reviewer to figure out general idea of what's being changed.  I think
the rest will be self-evident in the patch(es).

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

...

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

In my mind, this is even more reason for review.  If someone is doing
"big docs whackage" as you call it, there ought to be a way to test the
documentation to see what it will look like after all the "whackage" is
applied but before it's released.  Someone ought to read through the
updated form to make sure it doesn't have issues that break the docs.

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

"because people like working on it less" - should be rewritten to say
"because some people like working on it less".  I'm one of those people
who really enjoys doing docs and I am looking forward to continuing to
aid in the improvement of BZ docs.

As I see it, one of the big problems is how we often find that as
developers, we often don't file documentation update requests until just
before an official release rather than filing them in concert with our
updates.  I think it seems fair that any approval+ should have a bug
filed for documentation against the changes made (when required),
preferably with a review+ on those document updates.  That way, we don't
end up with 16-hour documentation code-a-thon's.

When documentation structure needs to be changed, or large sections of
the documentation need to be updated, I think it seems fair that bugs
should be required.  I'm actively creating a new Bugzilla document I'm
calling the PRTG - Pre-Release Testing Guide that is being written
completely from scratch.  If it's accepted and put into Bugzilla
documentation, each time an update is made that impacts pre-release
testing, it will be the reviewer's and approver's responsibility to make
sure that the PRTG updates are filed.

If we let documentation like the PRTG slip, it will quickly become
useless just like the Bugzilla Guide would if we ignored it.  Does the
creation of a PRTG make more work for all of us?  Yes and no.  It makes
more work making sure we're up-to-snuff with our own documentation, but
it also helps us make sure we're not releasing junk.  It acts as a guide
for developers, reviewers, administrators, and others.  Does the benefit
of having a PRTG outweigh the administrative cost of keeping it
up-to-date?  For me, it definitely does and I think the vast majority of
others will find that to be the case as well.

We disagree about your statement "because you can't break it".  IMNSHO,
one of three cases is always true when documentation and what's
documented disagree.  A) The documentation is broken, B) what's
documented is broken, or C) both are broken.    As I mentioned before,
it's generally harder to re-learn something that's correct than it is to
learn it right the first time.

Back to the topic - I feel that a review of documentation updates before
applying to CVS is necessary because 1) people are human and make
mistakes, 2) having a reviewer review gives another human a chance to
check over what is proposed, reducing the chance of publishing "stuff
that's broken", and 3) two heads are usually better than one in this
type of situation because the other person generally has a different
perspective and can offer insight that the person requesting the update
doesn't have.

---
Kevin Benton
Perl/Bugzilla Developer
Advanced Micro Devices
 
The opinions stated in this communication do not necessarily reflect the
view of Advanced Micro Devices and have not been reviewed by management.
This communication may contain sensitive and/or confidential and/or
proprietary information.  Distribution of such information is strictly
prohibited without prior consent of Advanced Micro Devices.  This
communication is for the intended recipient(s) only.  If you have
received this communication in error, please notify the sender, then
destroy any remaining copies of this communication.