contribute documentation

The criterion for a free manual is pretty much the same as for free software: it is a matter of giving all users certain freedoms. Redistribution (including commercial redistribution) must be permitted, so that the manual can accompany every copy of the program, on-line or on paper. Permission for modification is crucial too.

The Document Review Process

We would like to create a framework for documentation where contributors can add documents, get peer review, organize and maintain documents. Some contributors will be primarily developers who are documenting the code they work with. Others will be primarily wordsmiths. We hope to get these people working together. If your inital document is unpolished ask for help filling in technical details or polishing the language.

We also want to keep track of document status. Is the document complete or does it need some holes filled in? Is it complete but in need of editing? Is it finished and polished? Do parts of it need to be updated because of changes in the code? Should the document be retired because the code it describes was retired?

To facilitate the review process we have created a Documentation product in Bugzilla. Use this to keep track of problems with documents and to submit new documents for review. Bugzilla divides our documentation into three categories.

1. Mozilla developers - These documents are probably only useful for people who compile mozilla. It includes user manuals for code modules like The Complete nsCOMPtr User's Manual as well as documenting API's with javadoc and Commenting Mozilla for LXR to make LXR print descriptions in its file listings. We especially need bird's-eye overviews of the code for first-time Mozilla hackers.

2. Web Developers - This category overlaps the other two categories but should generally contain information useful to content creators, web site administrators, system administrators and people using Mozilla as an application development platform. XUL documentation goes here because even though it's needed by Mozilla developers, it's useful to others as well.

3. Users - Documentation reachable from Mozilla's Help menu.

Getting Involved

Here are some ways to help.

• If you just spent some time trying to figure out how part of Mozilla works, write down what you figured out. Others will probably have the same questions that you did. It doesn't have to be fancy. Post your findings to a newsgroup and get some feedback. If someone hasn't already come forward, post to the documentation newsgroup and ask for help htmlifying and polishing.
• When you contribute code, document it. Even if you don't have time to generate something fully polished, submit a draft and look for a volunteer in the documentation newsgroup to help polish it up.
• To get help, post to the documentation newsgroup. If no one offers to help right away, create a documentation enhancement request in bugzilla and mark it HELP WANTED.
• Search the newsgroups for pearls of wisdom. Sometimes you might find an explanation that should be added to an existing document or to the jargon list. If you notice the same questions being asked repeatedly, get them added to the FAQ. Often you'll find drafts that people posted but which never made their way to the web site. Offer to help the author polish the posting and check it in to the web site.
• Search Bugzilla for documentation bugs marked HELP WANTED in the Status Whiteboard field.

Style Guide

Use our Style Guide for guidance on creating content for our site. Our goal is to create content that works with a wide variety of browsers, even old, lame ones. We can't assume that people are using Mozilla to read our web site. In fact, many people read our site precisely because they can't yet use Mozilla. Keep the format of your documents as vanilla as possible. Feel free to write demo files to illustrate Mozilla's whizzy features, but make sure your document's main content is readable by everyone. In particular, use GIF images instead of PNG. Use HTML, not XML. Don't require the use of JavaScript except for demos since many hackers leave JavaScript turned off.

Checking In Documents

We are working on a copyright policy. In the future, we hope to institute a copyright policy that encourages information sharing, possibly like the Open Publication Licence or the Linux Documentation Project in which authors retain their own copyright while extending blanket reproduction and distribution privileges (subject to certain conditions). We are interested in hearing your opinions about this issue. Please post them to our documentation newsgroup.

We use CVS to manage the documents on our web site and use the same mechanism to grant access to the document tree as to the source tree. If you're submitting changes to a current document, check out the document via anonymous cvs. (Not set up yet. See bug 20962) Use cvs diff -u to make a patch file and submit the file to the owner of the document. If the document doesn't list its owner, click on the Last Modified link at the bottom of the page to see who has recently updated the page and ask them. If all else fails, mail webmaster@mozilla.org.

As with the source code, if you establish a track record of good work then you may be granted access to the repository, especially if you contribute documents and become their official owner and maintainer. To get access, you'll need to submit a CVS Contributor Form. Read mozilla.org Content And CVS for CVS information specific to our doc tree. The document Source Code Via CVS explains where to get a CVS client for your platform and has pointers to CVS documentation.