Bugzilla's documentation

[Gervase Markham]

Bugzilla's documentation has stagnated.

We can see the lack of change for the docs by looking at bzr. The last
time most of these files were edited was 5 months ago, and that was to
update the license header:
http://bzr.mozilla.org/bugzilla/trunk/files/head:/docs/en/xml/

If you go back before that, they were last updated in October 2011, when
we changed the software used to compile them:
http://bzr.mozilla.org/bugzilla/trunk/files/8074/docs/en/xml/

The actual _content_ of most of the files hasn't changed for ages.

Another telling sign is that new bits of documentation end up being
maintained on the wiki:
https://wiki.mozilla.org/Bugzilla:Move_Installation
  (one of the most frequently referenced when giving people help)
https://wiki.mozilla.org/Bugzilla:Mac_OS_X_installation
https://wiki.mozilla.org/Bugzilla:FAQ
etc. etc.

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. 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. I certainly
don't have the necessary software on my machine.

Making changes beyond editing some text requires knowing DocBook, or
doing cargo-cult copy and paste from another part of the docs. 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.

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.

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 could just say "hey, move it all to the wiki". However, IMO we also
don't want to lose the very useful ability to have frozen versions of
the documentation for each release:
http://www.bugzilla.org/docs/
AIUI, that would be hard to do on a standard MediaWiki like
wiki.mozilla.org.

I think what we need is a SCM-backed wiki, so people can edit the docs
either over the web, or by checking out the repo and editing the markup
directly. And we can make branches in order to deal with the multiple
versions issue. Ideally, we could back it with bzr and keep the docs in
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 did a blog post about this recently:
http://blog.gerv.net/2012/04/maintaining-documentation-in-a-wiki/
and the following software was suggested:

Hatta:   http://hatta-wiki.org/ (hg)
IkiWiki: http://ikiwiki.info/ (svn, git, bzr, monotone, hg, darcs)
GitIt:   http://gitit.net/ (git, darcs or hg)

I have since found:
PodWiki: http://www.daemon.de/PodWiki (rcs)
Foswiki: http://foswiki.org/ (rcs)

IkiWiki is the only one I've found that supports bzr, although it claims
to work best on git:
http://ikiwiki.info/rcs/
Getting the bzr support working might require manual work. However, it
is written in Perl. It also has a "wiki to HTML compiler", allowing us
to make static versions of the docs for the website archive.

Questions:

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

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

2) What do you think of my proposed SCM-backed-wiki solution?

3) Do you know of any other SCM-backed-wiki systems?

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla