making review/bug filing optional for some docs changes

[Benton, Kevin]

> Myk Melez wrote:
> 
> > 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
> >
> This sounds like a good idea, so long as there is some guidance given
to
> that group.  In the same breath, I would like to see a clarification
of
> the rules for docs changes.  Is it safe to say that a doc change by
> anyone needs ONLY a single review, no approval, and can be checked in?

Part of our discussion revolved around the concern that no matter how
updates are made, whether we still need accountability or not and should
updates still be logged in Bugzilla.  From my perspective, my answer
would be in the affirmative for these issues - we do need
accountability, that logging updates in Bugzilla should be a requirement
not only so people can see what's been done without having to use CVS,
but also in case something needs to be reverted, the place to track it
should (IMNSHO) always be in Bugzilla.  If we don't track it there,
we're likely to make the same mistake again.

Because we're maintaining enterprise-level software (and we advertise it
that way), we need to handle it as an enterprise-level entity would.  In
my experience at that level, to ensure high quality, any time a change
is put in place that could impact a customer, a release process needs to
be followed.  Because documentation is viewed by our "customers," I feel
it should be kept inside the release process.  This prevents human error
from leaking out.  Note I didn't say eliminate human error.  It's
possible that a reviewer could miss something.  On the other hand, if we
don't follow the release process, we can not benefit from catching
problems before they're released.  Therefore, with documentation being
such a high-visibility part of our product, I would suggest that no
matter who is making the documentation update, that it follow a release
process.  Whether that involves just one or two reviewers is not the
issue with me.  I think one reviewer on documentation is a fair balance
giving us the greatest flexibility to move quickly but still have a
check/balance for doc updates.

If someone is in a rush to get a doc update done, the review process
doesn't keep that person from making the update on their local system,
submitting the patch, then go on with life.  When the review comes up,
the reviewer can check the code in.  If it's a really small change, the
review should go very quickly and easily.  It would also make those
changes the kind of thing newly CVS authorized people could flex their
wings a little bit while the potential impact to Bugzilla should be
minimal.  It also educates new people to the review process.  So, if
someone misspells a word that gets published, a new reviewer could look
at the correction, check it, then review+ it with minimal effort.

I know that one developer we were talking with doesn't have a Bugzilla
installation local to their system.  What environment do they test
updates in?  How do we keep those updates from leaking into production?
I'm not against the concept at all, I just want to know that updates are
getting tested and there is no way for anyone except developers to see
an update until it's checked in.

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