Documentation Mailing List FAQ
This article contains frequently requested information about Mozilla and mozilla.org.
This article is divided into two parts. The first part provides general information about mozilla.org and rules for this forum. The second part is a guide for contributing to the documentation project. A third part is planned for translation.
This article is maintained by Daniel Wang <stolenclover@yahoo.com.tw> and is posted monthly to the documentation mailing list (also a newsgroup). This article was last updated on January 5, 2003.
Table of Contents
0. Preamble
0.2 Where is the latest version of this article?
0.3 How can I contribute to this article?
0.4 Can I ask the author questions by e-mails?
0.5 Credits
Part I About this Mailing List and Mozilla.org
1. About this Mailing List
1.2 Why is this newsgroup
publicbut the user support newsgroups are on a secure news server?
1.3 Where are the end-user support forums?
1.4 How do I subscribe/unsubscribe from this mailing list?
1.5 Many people have offered to help with documentation in this forum, what happened to them?
1.6 So how do I get help with my documentation?
2. Netiquettes
2.2 Is cross posting allowed?
2.3 Subject matter
2.4 Should I use my real e-mail address?
2.5 Can I post attachment here?
2.6 Can I post HTML messages here?
Part II Documentation
3 About the Mozilla Documentation Project
3.2 How is the Mozilla Documentation Project organized?
3.3 Most of documentation on Mozilla.org site is outdated, why?
3.4 Is there any plan to update the documentation?
3.5 Zope - the future of mozilla.org?
3.6 How do I request documentation?
4 Copyright and Legal Issues
4.2 So who owns documentation on mozilla.org?
4.3 How about the Open Publication License?
5 How to Contribute
5.2 What needs to be done?
5.3 How do I modify mozilla.org site contents?
5.4 How do I modify Netscape site contents?
5.5 How do I check out Mozilla help files
5.6 How do I check in Mozilla help files?
5.7 Where else can I publish my Mozilla documentation?
6 Writing Online Documentation
6.2 Is there any style manual for mozilla.org documentation?
6.3 A small note on HTML format.
7 Mozilla Help
8 Quality Assurance
Copyright © 2002-2003 by Daniel Wang, all rights reserved. This material may only be distributed or used under the terms and conditions set forth in the Open Publication License (OPL), version 1.0 or later (the latest version is available at <http://opencontent.org/openpub/>).
This article is offered in good faith and in the hope that it may be useful, but it is not guaranteed to be correct, up to date, or suitable for any particular purpose. Neither the author nor any contributor of this document claim any affiliation with mozilla.org or its financial supporters. None of the parties mentioned above accepts any liability in respect of this article or its use.
0.2 Where is the latest version of this article?
This article is not archived in any permanent place. The latest version of this article will be posted to this mailing list.
0.3 How can I contribute to this article?
If you would like to contribute to this FAQ, please send an e-mail to Daniel Wang <stolenclover@yahoo.com.tw>. All contributors will be listed in the credits.
0.4 Can I ask the author questions by e-mails?
Please do not ask me questions via e-mail. Post questions to an appropriate public forum, where they will be read (and possibly answered/discussed) by many people with more expertise than me. Think carefully before posting; you will get more useful answers if you post clear, complete questions.
If you think something already in the FAQ needs clarifying, or if you would like to offer a concise, well-written answer to a frequently asked question that is not yet in the FAQ, feel free to send me an e-mail.
Due credits of this article are to Daniel Wang (writing and editing) and for the following people for comments and suggestions: Gervase Markham, Nuno Silva, and Henri Sivonen.
Portions of this article are based on:
Red Drag Diva, Is this the right newsgroup for me to post to?
<http://velvet.net/~fun/mozilla/ngfaq.txt> (June 9, 2002)
Mosedale, Dan READ BEFORE POSTING: netscape.public.* and tech support
(general mailing list) (June 2, 1999)
Part I About this Mailing List and mozilla.org
Section 1 About this Mailing List
1.1 Is this the right place to ask where help files are?
The mozilla.org mailing lists are solely for use by developers working on the source code to Mozilla, the open-source cousin of Netscape Communicator. Postings about problems that you are having using your browser do not belong here. Questions about how to do some specific thing with your browser do not belong here. In short, unless you are in some way contributing work (code, bug fixes, documentation, localization, feature suggestions, etc.) to the Mozilla project you probably don't want to post here.
See <http://www.mozilla.org/community.html> for a detailed explanation list of available forums to help you decide where your posting belongs, as well as usage guidelines.
1.2 Why is this newsgroup public
but the user support newsgroups are on a secure news server?
The newsgroup naming is a historical accident; when mozilla.org first started,
only developers visited Mozilla newsgroups. Public
was used
as a reminder to Netscape staff that the forums are open to general public (as
opposed to being internal).
User support newsgroups are put on a secure news server by intention. To prevent excessive spams and duplicate posts, it is customary for companies (e.g. Microsoft) to put their user support forums on a secure server.
N.B.
We understand that the word public
is misleading.
An alternative newsgroup naming scheme has been proposed (read
<http://www.mozilla.org.uk/newsgroups.txt>).
Before the proposal is realized, we ask you to post user questions in the forums
listed in the next section.
1.3 Where are the end-user support forums?
You may ask for help with your browser (or another Netscape product) at the the Netscape User Group (NUGgie) newsgroups. More info about these can be found at <http://help.netscape.com/nuggies/>. In order to access them, you'll need a newsreader that can access secure newsgroups (such as Mozilla). Here are a few links to take you directly to browser-related newsgroups:
Netscape Seven
Windows <snews://secnews.netscape.com:563/netscape.netscape7.windows>
Macintosh <snews://secnews.netscape.com:563/netscape.netscape7.macintosh>
Unix/Linux <snews://secnews.netscape.com:563/netscape.netscape7.unix>
Netscape Four
General <snews://secnews.netscape.com:563/netscape.communicator>
Macintosh <snews://secnews.netscape.com:563/netscape.macintosh>
Unix/Linux <snews://secnews.netscape.com:563/netscape.communicator.unix>
Mozilla User Newsgroups
General <snews://secnews.netscape.com:563/netscape.mozilla.user.general>
Windows <snews://secnews.netscape.com:563/netscape.mozilla.user.win32>
Macintosh <snews://secnews.netscape.com:563/netscape.mozilla.user.mac>
Unix/Linux <snews://secnews.netscape.com:563/netscape.mozilla.user.unix>
Mozilla Help on the Web
Mozilla 1.0 User FAQ <http://mozilla.org/start/1.0/faq/>
Mozilla 1.0 Guide <http://mozilla.org/start/1.0/guide/>
Other help pages <http://mozilla.org/start/1.0/faq/enduser.html>
1.4 How do I subscribe/unsubscribe from this mailing list?
If you choose to subscribe to this mailing list rather than reading it as news, send an e-mail to
mozilla-general-request@mozilla.org
with subscribe
in the subject. Likewise, to unsubscribe, put unsubscribe
in the subject.
1.5 Many people have offered to help with documentation in this forum, what happened to them?
Unfortunately, some of people who offered to help with documentation simply disappeared due to lack of follow up. There is little we could do about it as people who frequent this forum are too tied up with other commitment to walk new comers through the documentation process.
Also, many people who contribute to documentation are also involved in other areas of development, so they can only contribute on a hit-and-run basis. Some who disappeared for a while did come back later on.
1.6 So how do I get help with my documentation?
Other than what little this forum can offer, unfortunately you will have to rely on what you already have known.
It depends on the convention in the mailing list. In this forum, the general preference is that reply should follow or intersperse with the quoted message.
No, most people who read this forum also read other Mozilla forums; you should post only to the forum most appropriate for your subject. You should not cross-post your messages in newsgroups in different servers, especially across end-user newsgroups (on a secure server) and developer newsgroups (on an open server).
Many people using this mailing list/newsgroup receives hundreds of messages
a day. To ensure efficient communication, identify your subject matter
clearly in the subject line. Subjects like a question
and
Mozilla problem
are unacceptable.
2.4 Should I use my real e-mail address?
Yes, please.
2.5 Can I post attachment here?
Try not to attach any thing to your message (remember that this forum is also a mailing list). If you have any HTML documentation that you wish to share with others, upload it to the Web and post a link to it.
2.6 Can I post HTML messages here?
No, you should post plain text messages here.
Part II Documentation
Section 3 About the Mozilla Documentation Project
3.1 Where is the documentation projection site?
The project site lives at <http://www.mozilla.org/docs/mdp>
3.2 How is the Mozilla Documentation Project organized?
There is very little, if any, coordination among documentation contributors. Much of documentation activities center around this mailing list and Bugzilla <http://bugzilla.mozilla.org> where documentation bugs are reported and discussed.
3.3 Most of documentation on Mozilla.org site is outdated, why?
To some degree, the fact that Mozilla.org software develops faster than documentation staff and contributors can keep up is a good thing. However, documentation contributors are not entirely happy about this, and we welcome any help on keeping our documentation fresh and up-to-date.
3.4 Is there any plan to update the documentation?
Unfortunately there is none as there is little coordination among documentation contributors. Maintenance mostly depends on the private agenda of each individual documentation writer, most of whom are spending 110% of their free hours making contribution to mozilla.org.
3.5 Zope - the future of mozilla.org?
Information not available. Contribution welcome.
How do I request documentation?
Before requesting documentation, you should first search
mozilla.org, the Web, the
help files, and the source code
to see if the information you want is already available. If the information
is unavailable, or if it is available but has not been published in
accessible forms in mozilla.org, you may file a bug report. See
8.4 How do I file a bug report?
Section 4 Copyright and Legal Issues
4.1 What license is Mozilla.org documentation licensed under?
Currently there is none (see bug 28828 Need license for documentation
<http://bugzilla.mozilla.org/show_bug.cgi?id=28828>
and bug 19027 Figure out copyright of web site vs. specific content
<http://bugzilla.mozilla.org/show_bug.cgi?id=19027>)
4.2 So who owns documentation on mozilla.org?
Documentation contributed by Netscape or mozilla.org belongs to the respective organization. For documentation by volunteer contributors, the ownership is pretty much a mystery.
4.3 How about the Open Publication License?
Open Publication License <http://www.opencontent.org/openpub/> could serve as a good template for documentation license on mozilla.org. Now if we could only get Mozilla lawyers involved...
Documentation status used to be tracked at <http://www.mozilla.org/docs/mdp/docstat.html>. Unfortunately the page is very out of date.
To find out if a documentation is being worked on, you should first find out if there is a bug report for it at bugzilla <http://bugzilla.mozilla.org> and if someone is working on it. Sometimes a person may state that he or she would work on a documentation bug but never come back with more comment. In that case you should contact that person to pick up whatever work the person has done.
Also, you should post to this forum to see if someone is already working on the documentation you want to do.
You may do any documentation you deem relevant to Mozilla and mozilla.org. The topic could be development process, end user manual, source code, open source movement, Web development with Mozilla, or Mozilla evangelism. There is no priority list for documentation.
The following are some useful links:
Better End User Documentation bug tree
Make it easier to become a Mozilla Contributor bug tree
Working plug-ins status and files needed for Mozilla bug tree
ReadMe files bug tree (need a tree)
Documentation Status table
open documentation bugs list
5.3 How do I modify mozilla.org site contents?
At the bottom of every mozilla.org document, there should be a
Edit this Page
link. Follow the link to make modification
to the source code. Then choose the Review Changes
button and
save the source change to as a text file (.diff).
If you have mozilla-org cvs access privilege, you may commit the changes directly. Prior to that, be sure that you have announced the up-coming changes and have checked with the nominated owner of the page, or the last person to modify it.
If you do not have check-in privilege, you may save the change as a .diff file and post it as a patch to the relevant bug report (create a new report if necessary) to have someone else check it in for you.
See also mozilla.org content and cvs
<http://www.mozilla.org/README-cvs.html>
and mozilla.org style guide
<http://www.mozilla.org/README-style.html>.
5.4 How do I modify Netscape site contents?
Who has access privilege to Netscape site content?
5.5 How do I check out Mozilla help files
See http://www.mozilla.org/source.html about checking out help files from the cvs.
See also Open Source Development With CVS: A Day With CVS
<http://cvsbook.red-bean.com/cvsbook.html#A_Day_With_CVS>
for help with using cvs.
5.6 How do I check in Mozilla documentation?
You need cvs check-in privilege. For documentation on the Mozilla Web site, send an e-mail to <endico@mozilla.org> to find out the procedure. For anything in the source tree, including the Mozilla help files, refer to <http://www.mozilla.org/hacking/>.
5.7 Where else can I publish my Mozilla documentation?
Other than mozilla.org, you can also publish your work at
<http://moz.zope.org>,
which is more open
than mozilla.org.
Of course you can publish your file elsewhere and have Mozilla Web site link to it
Section 6 Writing Documentation
6.1 Why isn't DocBook used for documentation format?
Because it would be severe overkill.
6.2 Is there any style manual for mozilla.org documentation?
The mozilla.org Style Guide
lives at
<http://www.mozilla.org/README-style.html>.
It's only a guide, so there is no rule that all contributed documentation must conform to it. However your are encouraged to read it before writing your documentation.
Also check out Writing Documentation
<http://moz.zope.org/contribute/writing/walkthrough>
6.3 A small note on HTML format.
This is just a reminder.
mozilla.org automatically insert wrapper on its site contents (the navigation bar and the banner). The wrapper code works with HTML 4.01 Strict and Transitional but will invalidate other flavors of (X)HTML, therefore your file should be valid HTML 4.01 Strict or Transitional.
Also, at present the character encoding needs to be declared in a <meta> tag because no one has come forward with details on getting it in the HTTP headers on mozilla.org.
7.1 How does Mozilla Help system work?
Information not available. Contribution welcome.
8.1 What is Quality Assurance?
Quality Assurance (QA) in respect to mozilla.org is is synomyous to quality management. The notion of quality assurance (and quality management as a whole) can be approached in two ways: as standards and as processes.
Quality is related to standards. Common to all forms of quality management is the basic product testing which involves testing and verifying a product against certain requirements and specifications, or collectively called quality standards. Quality management therefore involves three tasks: setting standards, conforming to standards, and achieving standards, all three of which can be seen in various Mozilla development areas.
Achieving standards (or QA) means that we make sure our software and documentation conform to quality standards prior to public releases. An obvious evidence of this are the various testing procedures carried out regularly.
Conforming to standards (or QC) means that we control our development process to ensure that our efforts lead to quality products in the most efficient manner. At mozilla.org, the mandatory uses of Bugzilla and cvs, and the review-super-review process are two example of QC processes.
The most difficult part of quality management is setting and raising standards (or QI). It involves establishing new quality standards, either by using industry standards such as the W3C User Agent Accessibility Guidelines 1.0 or by writing our own, and establishing better quality standards. Examples of these are various development plans on mozilla.org.
Quality is also related to processes. Quality management is establishing, following, and improving procedures (or how we do things) so that what we do is in itself quality work.
Not only is quality management a process, in fact, quality is the process.
8.2 So what is QA in documentation?
Notwithstanding the previous confusing, personal rant, QA to documentation is actually quite simple:
- first, we find out what we need to do, either by check with Buzilla for open documentation bug reports or requests, or by asking in the documentation newsgroup;
- then, we write, review, and edit documentation;
- we then post it for peer review;
- when reviewing, we
- look for grammer and spelling errors,
- make sure the language is accessible to the intended audience,
- check for coherence and integrity (are section numbered correctly?),
- review the content for accuracy,
- write test cases or establishing test procedures to verify content,
- verify Web links, and
- validate the format (if it is HTML);
- we then vote for quality works to be reviewed by approved reviewers;
- then then release it to the Mozilla site or help files; and
- after release, we maintain our documentation by
- follow the same review procedures described eariler,
- perform tests to verify the content,
- check status of linked bugs or documentation,
- look for what need to be added or removed, and
- if necessary, file a bug report to make changes.
Naïvely speaking, Bugzilla <http://bugzilla.mozilla.org> is a tool mozilla.org uses to track bug reports.
Bugzilla fulfills many roles. It is the forum for discussing features, triaging bugs, and suggesting solutions. It is the place where patches (code fixes) are posted and reviewed before they are committed to the source tree. Bugzilla is used for tracking bug reports and, more generally, the quality and state of affair of Mozilla software. Bugzilla is also, in many ways, the primary communication interface between Mozilla developers and end users.
Most importantly, Bugzilla is the central management tool for the entire mozilla.org efforts. We use Buzilla to delegate responsibilities to mozilla.org staff and contributors by means of bug assignments. By this, we establishes a community hierarchy relating developers to one another. Like it or not, the patch-review-super-review process establish who is the king (or queen). The all important bug tree feature (see example) help mozilla.org staff and contributors in different development areas relate their work to that of others. Where purposeful developer coordination is lacking, Bugzilla serves as a major communication medium for Mozilla developers. Bugzilla is used to track the progresses of development plans; most mozilla.org plans, such as the various roadmaps, make direct references to Bugzilla.
8.4 How do I file a bug report?
If you want to file a documentation bug report for error correction, you should first check if the bug has been reported:
-
For contents on mozilla.org, type in the URL and choose Search:
If the bug has not been reported, you may file a mozilla.org:webmaster@mozilla.org bug report.
-
For contents on Mozilla online Help, in the Help content window press Ctrl+I. From the Page Info window, copy the file name part of the help file URL (for example,
welcome_help.html
inchrome://help/locale/welcome_help.html.
) Type the file name in and choose Search:If the bug has not been reported, you may file a documentation:user bug report. Make sure you put the entire URL of the help file in the URL field. (Note the the component browser:help is for the help file system, not the Help contents.)
If you want to request documentation be written, you should first search mozilla.org, the Web, the help files, and the source code to see if the information you want is already available. If the information is unavailable, or if it is available but has not been published in accessible forms in mozilla.org, you may file a bug report.
If you want your documentation published on your one server to be be
linked to a mozilla.org document, send a request e-mail to the contact
person of that document. If the document does not indicate who the
contact person is, follow the Document History
link at the end
of the document and send the e-mail to the last person who changed the
document. If you still don't know who to contact, send the e-mail to
Dawn Endico <endico@mozilla.org>.