Bugzilla's documentation

[Gervase Markham]

[I had hoped to talk about this in the meeting, but I had to leave.]

Bugzilla's documentation has had the same structure since at least
Bugzilla 2.16 in 2006, and probably earlier. Until recently, it was
maintained in hard-to-compile XML, which led to strong incentives to
either not update the docs, or update them in the most minimal way
possible e.g. by adding a paragraph of text in the middle somewhere. Or,
people documented things on the wiki instead because it was easier -
there are several documents on the wiki which should be part of the
manual.[0]

The recent move to ReST removed some extraneous bits like the glossary
but (by design) did not make any significant change to the content or
organization. So the result is still long-winded, full of conflicting
"voices" and not very easy to use.

Now that we've moved to ReST, we have the capability to rearrange,
rethink and rewrite the documentation much more easily. Some possible ideas:

* Make a better way of getting a set of install instructions which
contain only the parts relevant to you (there are several ways this
could be achieved)

* Include resources which are currently external but really belong in
the manual (we'd need to seek authorial permission for licensing reasons)

* Remove obsolete stuff (e.g. some of Troubleshooting, Contrib)

I did try and do this once before, many years ago. Even then, there was
no shortage of improvements to make! However, IIRC it foundered at the
review stage - reviewing documentation changes as a massive patch proved
to be very hard work, lots of people felt it had to be absolutely right
for them before it was checked in, and one or two controversial issues
held it up until it died a sad death by asphyxiation. I don't want this
to happen again.

So here is my proposal: if I commit to doing the hard work of
reorganizing and rewriting the docs on a branch, incorporating external
material and generally making them fit for the year 2014, will one or
two other Bugzilla devs commit to reviewing them _as_an_entire_document_
(as opposed to as a patch), and will everyone else consent to trust me
and that person to the extent that we can check in the branch after it
passes their review, and fix up any parts that you don't like later?

If you are willing to be the reviewer, say so. And if you _object_ to
trusting me and the reviewer to improve the docs together, say so.

Gerv

[0] E.g. https://wiki.mozilla.org/Bugzilla:Moving_From_CVS_To_Bazaar or
some of the stuff in https://wiki.mozilla.org/Bugzilla:FAQ .
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla