(This page will include the Mozilla.org banner at the top.)
Welcome to the Mozilla.org Documentation Roadmap. Like the Mozilla.org Roadmap, this document is intended to set a course for the future of the Mozilla project. This document outlines our overall goals for documenting the Mozilla suite and related tools Mozilla.org supports.
We have begun work on a catalog, similar to dmoz.org, for Mozilla documentation. I would propose that we continue to emulate the dmoz.org model, including borrowing the dmoz.org search engine features and openly soliciting human editors for our links. The current dmoz page for Mozilla can be found at http://dmoz.org/Computers/Software/Internet/Clients/WWW/Browsers/Mozilla/.
Ian Oeschger suggests instead using dmoz's Mozilla section directly for this purpose. I'm less confident in this idea, as our documentation effort may need some metadata as well (when we verified the documentation, what bug number applies to it, et cetera).
John Keiser is investigating enhancements to ZOPE (see below, under Tools) as a planned base for our catalog.
Past trends in documentation have been to loosely write documentation for three groups: Mozilla developers, web developers, and end-users. This is a good idea, and we should have a section of our catalog specifically organized along these lines. Our discussions in #documentation leave us to believe we probably need four major areas of focus:
Nuts & Bolts may require a new category in the Documentation component at Bugzilla. However, as we hope to modify LXR for this (see below, under Tools), the general consensus to date is that we do not need this.
This is where the legions of people who don't directly contribute code to Mozilla come in. You don't have to know C++ to do documentation (except probably for large parts of the Nuts & Bolts, in the C++ code). Basically, if you know how it works, great! If you can easily find good documentation on it, great! If not, that's where we need you.
We need people for all of the following tasks:
(Let's strongly consider creating links to documents for each of these subjects, telling people how to do them.)
Most of these do not require you to know C++ or XPCOM! You do not have to be a coder to write, edit, or verify documentation. In some cases, that obviously helps, but in others it may be just a matter of clicking on a testcase link and following the directions!
Some of the documentation we expect to be out of date; please feel free to write testcases for them, and verify that the behavior is as described. If it's not, write up the changes to a local copy of the documentation, and check Bugzilla to see if there's already a bug for that file. If there's no bug on file, file one! If there is a bug on file and no one's currently working on it, attach the new version to the bug. If you can create a CVS patch for such documentation, please do so! This assists us greatly in r= and sr= for the patch (something we will probably start doing on a rigourous basis soon -- see below under Policies).
Regarding screenshots: generally they are considered a good idea for a page that has been found after searching, but a screenshot does not assist in searching for a page. Moreover, they create problems for translations of a documentation page (if the screenshot is in English and the person reading the documentation can only read Japanese, for example). Keep screenshots small in terms of file size and quantity, please!
Looking for a list of areas we need help documenting or cataloging? (I'll add a link for this when someone gives me such a document.)
There's a few things we will probably need to do before we start an "all-hands" push on documentation.
The largest concern we've heard to date regarding our proposed use of ZOPE for documentation is from Dawn Endico. She is requiring a blame log for documentation, so John Keiser is working with a few other people in either tying ZOPE to Mozilla.org CVS or adding a blame log feature to our ZOPE.
Ideally, we should launch a DocWeek very soon after we clear most of the bugs mentioned in this Documentation for End Users Roadmap. The date for DocWeek is TBA, but probably on a Monday. It should start at 8 a.m. Pacific Time, to last seven days with special promotions on the mozilla.org home page and #mozilla, #mozillazine on IRC. We'll work out scheduling of supervisors for this DocWeek as time progresses, in the DocWeek bug.
Timelines for various portions of our documentation will revolve primarily around feedback from the community at large. Again, this may largely be a case of indexing and cataloging our current documentation. Please do not e-mail me to make suggestions on what needs documenting the most; file it in n.p.m.documentation.
This roadmap will be updated as time allows. Those who primarily drive Documentation are free to edit or reject this roadmap document as they see fit. (In other words, don't necessarily count on me being around to make changes to this roadmap; grab it from the latest attachment to bug 151101, update it and reattach it to the bug.) If you have a suggestion for this roadmap document (no matter how small), please file it as a comment in bug 151101.
Alexander J. Vincent, jscript@pacbell.net