(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).
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. However, I propose that we really need five categories instead of three:
The two new categories (Nuts & Bolts, and Product Developers) may require new categories in the Documentation component at Bugzilla. Feedback from the community regarding these two categories is strongly requested on this point.
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:
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 almost certainly start doing on a rigourous basis soon).
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!
There's a few things we will probably need to do before we start an "all-hands" push on documentation.
For this roadmap document, we might want to seek a driver's a= to ensure that our efforts correlate to Mozilla.org's goals, and to assist us in getting promoted on Mozilla.org itself.
Ideally, we should launch a DocWeek very soon after the publishing of this Documentation Roadmap. I would recommend a target launch for Docweek being the Monday following the first Friday after this Roadmap is published. 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