Bugzilla's documentation

[Frédéric Buclin]

Le 22. 06. 12 18:52, Gervase Markham a écrit :
> Why are people not updating the docs? Why are new things being written
> on the wiki instead? The primary reason, I suggest, is that editing the
> documentation is difficult.

That's not the single reason. Being able to edit the documentation on
wiki without having to ask for review plays a major role too, I think.
Everyone is free to write what he wants without having to ask anyone's
approval. If it needed review, contributors wouldn't bother writing doc,
even on wiki.

But there are two major disadvantages of free editing:
1°) Some contributors can write wrong information (unintentionally),
which is especially critical when talking about how to upgrade or how to
manage the security of your installation.

2°) The information can become messy pretty quickly, everyone starting
his own page despite the information is already duplicated elsewhere,
even partially. This makes it harder to find what you want. Also, some
information is very old, despite being on wiki.


 It's XML and DocBook-based, and compiling it
> to validate one's patches and even view what they look like in the HTML
> version requires installing a variety of esoteric packages.

This last statement is no longer true. Instead of Jade + a variety of
other tools, you now simply need xmlto. It's now much more easier to
compile the documentation than it was before.


> You have
> very little control over the look and feel of the resulting HTML which
> most people read, and it's not pretty by modern standards anyway.

The output is much better with xmlto than with Jade. We also have a
higher control on the output. Just compare:

Jade: http://www.bugzilla.org/docs/4.2/en/html/installation.html
xmlto: http://www.bugzilla.org/docs/tip/en/html/installation.html

If we are simply writing plain text, it won't look better on wiki.


> I have made several patches to Bugzilla over the last year and I didn't
> even think of checking the docs, never mind patching them. From the
> commit logs, it seems like I'm not alone.

Having the documentation on wiki won't help. People who don't care about
updating the documentation will still not care. Depending on what is
changed, reviewers *have to* ask to update the documentation at the same
time. If they don't, they don't do their job correctly. At the very
least, they are responsible to set the documentation flag to "?" to put
it in our radar. Also, it's currently possible to have the doc changes
included in the same patch as code changes. With having everything on
wiki, this won't be possible anymore.


> If we want to have accurate and useful documentation for Bugzilla, we
> need to make editing the documentation a _much_ more accessible process,
> certainly for developers and even for knowledgeable users.

We agree on that, assuming not everybody starts writing doc at the wrong
place in an unmanageable way, see above. Can you easily write a table of
contents with several levels of depth and an index with wiki, which are
updated automatically? Just compare these two pages:

official doc: http://www.bugzilla.org/docs/tip/en/html/index.html

wiki: https://wiki.mozilla.org/Bugzilla:Home_Page

The first one has a clear structure which is updated automatically and
which reviewers have approved. The second one has no structure. It's a
mess which I don't even bother to read. And it requires manual changes.
This means you could write a great page and nobody would know it exists
if you don't add it manually to the table of contents.


> the same repo as the source, as now. But I still think it would be
> better even if we had to use a different SCM and so a different Mozilla
> repo. (Mozilla has svn, hg, bzr, cvs and (soon) git repos.)

I personally wouldn't want to use another repo for the documentation. We
already have CVS for bugzilla.org, one bzr repo for the Bugzilla core
code, and another bzr repo for Selenium + QA code. A 4th one is a bit
too much.


> Questions:
> 
> 0) Do you agree with my initial assertion that our docs have stagnated?

Yes.


> 1) Do you agree with my diagnosis of the problem?

Only partially.



> 2) What do you think of my proposed SCM-backed-wiki solution?
> 3) Do you know of any other SCM-backed-wiki systems?

No, twice.


LpSolit