Bugzilla's documentation

[Mark Côté]

Sounds like a great idea!  In addition to your suggestions, I would vote
for a section on WebServices.  The associated API docs are confusing at
first; a readable section explaining the basic concepts and how to use
the API docs would, I think, be really useful.  I always feel bad when
people ask for docs on the new native REST and I have to point them to
http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/REST.html.

(That reminds me that I still have to move around the REST docs on the
wiki...)

Anyway, I am not a dev, but I would be willing to read through your new
docs at least for consistency, style, grammar, etc.

Mark

On 2014-05-01, 11:14 AM, Gervase Markham wrote:
> [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