making review/bug filing optional for some docs changes

[Shane H. W. Travis]

On Fri, 18 Mar 2005, Luis Villa wrote:

> Wow. That sounds incredibly stiflingly unfun. Glad people are paid to
> work on this now...

Nobody is getting paid, which means nobody can be forced to work on anything
with the threat of the wage-stick hanging over their head. As such, to some
degree, documentation has been abandoned by most people because it's
'un-fun', and not seen as a 'real' contribution.

(Even Max once said to me, during a period when I was quite productive on
the codebase, "Wow, you're going to catch up to me in real bugs fixed soon!"
The implication being that documentation bugs aren't 'real bugs'...)

That is, in part, what this discussion is about; lowering the bar so that
documentation patches can get in more quickly/with less effort, so hopefully
things stay more current.

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.

This, then, is part of my problem. It seems like people are saying, "I'd be
happy to contribute! I just love writing documentation... but you've got all
these messy *procedures* in the way that are stopping me." The underlying
message seems to be, "If I can't have complete and free access with nobody
else restricting me, questioning me, or second-guessing me... then I just
won't do anything at all."

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.

The prevailing argument is that documentation could be fixed later... and I
agree that it could, *if people notice that it needs fixing*. The people
reading the docs are not, typically, people who are completely conversant
with Bugzilla. They are the people who need help with Bugzilla. They are the
ones who don't know how things work, and are seeking more information. How
are they supposed to know if the docs are right or wrong? Those who do
reviews, however, are (ostensibly) more aware of Bugzilla than your average
user, and therefore will have a better chance of finding such things.

I have University credentials as both an English Teacher and a computer
programmer. I have contributed quite a few code improvements to Bugzilla. I
have fixed more documentation bugs in the last six months than anyone else
has in the last 30. If anyone was going to be awarded Trusted Docs Hacker
status, I'd like to think that all of those things would put me on short
list... and not only do I not want the honour, I don't think that the
position should even exist. I agree with Dave that certain folks should be
allowed to go in and fix typographical/presentational things, but I strongly
believe that all content and structural changes should be reviewed by
another human being who cares enough about documentation to want to be on
the Documentation Review Team.

Just because a girl isn't as popular, doesn't mean she should 'put out'
more so people will be willing to be with her; just because documentation
isn't perceived as a glamorous (or even, sometimes, valued) contribution
doesn't mean we should relax the standards on it.

All, of course, IMHO.

Shane H.W. Travis       | The greatest of all mistakes is to do nothing
travis at sedsystems.ca    |  because you can only do a little.
Saskatoon, Saskatchewan |   Do what you can.  -- Sydney Smith