Documentors' Guide
- Miscellaneous facts about the Bugzilla Documentation
- Finding where we need help
- How to edit documentation
- Getting your change contributed
Bugzilla is a moving target. Over the last few years, there have been a lot of changes to Bugzilla, and there continue to be a lot of changes to Bugzilla. This makes it very challenging to keep the documentation current. Most people know that developers tend to write bad documentation, and many times they'd rather move on to the next chunk of code instead of writing documentation to go with the code they just wrote. This is why a lot of companies have separate technical documentation departments that take care of writing the manuals. We've found that Bugzilla's documentation really benefits by being done the same way. Often the fact that the person writing the docs doesn't already know how the feature works results in better documentation because of the documentor having to quiz the developer on how it works, and being able to present it in a "less technical" way.
Over the last few years, we've had good success having separate people working on documentation than the rest of the code. Unfortunately, people move on to bigger and better things (well, not always better, one of them was deployed in Iraq), and our Documentation crew is a little short-staffed at the moment. This is where you come in! If you have technical writing experience, or are just good with words, we want your help!
Miscellaneous facts about the Bugzilla Documentation
We currently maintain separate documentation for 4 different versions of Bugzilla: 2.20.x, 2.22.x, 3.0.x and the current development version (3.1.x at this time). We try to keep the 4 versions of the documentation in sync with each other as much as possible, differing only in details that don't apply to all of them (for example, new features would only get documented in the versions of the docs corresponding with or newer than the version of Bugzilla in which that feature first became available).
The documentation is maintained in Bugzilla's CVS in DocBook XML 4.2 format. The web site checks CVS for changes to the source XML every 15 minutes, and the HTML, text, and PDF versions of the docs are generated by the web server any time changes to the XML are detected. So the documentation on the web site is always going to be accurate within a few minutes to what is in CVS at the time.
Finding where we need help
There are a few different queues where we collect information in Bugzilla about where we need documentation written. Besides having a Documentation component in the Bugzilla product on bugzilla.mozilla.org, we also have a series of documentation flags which can be requested on code-related bugs to indicate that the checkin for that bug included changes to the code that also need changes made to the documentation to compensate for it.
Lists of documentation bugs:
- Open bugs in the Documentation Component
- Resolved code bugs that need documentation written: Some of these may overlap - see the flags on the bugs when you view them.
How to edit documentation
Get your own copy of the source
The source for the Bugzilla documentation is available via anonymous CVS. To make sure you're working off the current version of the documentation from each branch, you'll need to use CVS to get it. We recommend that you check out all four branches (or at least the branches that apply to the bugs you are trying to address). The following example shows how you would check out all four versions:
$ export CVSROOT=:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot $ cvs login Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot CVS password: ← just hit Enter here $ mkdir bugzilla-docs $ cd bugzilla-docs $ cvs checkout -P -d tip mozilla/webtools/bugzilla/docs output omitted $ cvs checkout -P -d 3.0 -rBUGZILLA-3_0-BRANCH mozilla/webtools/bugzilla/docs output omitted $ cvs checkout -P -d 2.22 -rBUGZILLA-2_22-BRANCH mozilla/webtools/bugzilla/docs output omitted $ cvs checkout -P -d 2.20 -rBUGZILLA-2_20-BRANCH mozilla/webtools/bugzilla/docs output omitted
Find your file
The first step in editing the documentation is to find out which source
file contains the change you need to make. In many cases, if you're viewing
the documentation on the web site, the source file will be the same name as
the html file, but with an xml extension on the end
instead. If there is no xml file with a matching filename, click
the "Up" link at the bottom of the document, and try again with the filename
of the parent document.
This document is still under construction, and more details will be added here soon!
Getting your change contributed
When you have a patch ready, attach it to the related bug. Then click the
"Edit" link to view the patch details, and choose the "?" marker next to the
review flag. Enter documentation@bugzilla.bugs into the text
box next to it, and click Submit. Someone from the core team will be along
before too long to review your change, and will either check it in or suggest
changes they would like you to make to it.
Reviewers: You can view the documentation review request queue.