Documentation FAQ

dwx Thu, 12 Dec 2002 23:13:26 -0800

Documentation 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 <[EMAIL PROTECTED]> and is posted monthly to the documentation mailing list (also a newsgroup). This article was last updated on December 12, 2002.

*Full Table of Contents*

0. Premble
0.1 Copyright and disclaimer
0.2 Where is the latest vesion 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.1 Is this the right place to ask where help files are?
1.2 Why is this newsgroup `public' but the user support newsgroups are on a secure news server?
1.3 Where are 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.1 Is top posting allowed?
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?

3. Contribute
3.1 Do I have to be a programmer to contribute?
3.2 I have an idea on improving Mozilla, where can I post my idea?
3.3 I think I have found a bug in Mozilla, what do I do?
3.4 How do I make a donation to Mozilla.org?

_Part II Documenation_

4 About the Mozilla Documentation Project
4.1 What's the documenatio projection site?
4.2 How is the Mozilla Documentation Project organized?
4.3 Most of documentations on Mozilla.org site is outdated, why?
4.4 Is there any plan to update the documentation?
5 Copyright and Legal Issues
5.1 What license is Mozilla.org documentation licensed under?
5.2 So who owns documentations on mozilla.org?
5.3 How about the Open Publication License?
6 How to Contribute
6.1 Who is doing what?
6.2 What needs to be done?
6.3 How do I modify mozilla.org documentation?
6.4 How do I check out Mozilla help files
6.5 How do I check in Mozilla help files?
6.6 Where else can I publish my Mozilla documentaion?
7 Writing Documentation
7.1 Why isn't DocBook used for documentation format?
7.2 Is there any style manual for mozilla.org documentation?
8 Mozilla Help
8.1 How does Mozilla Help system work?

Appendix A mozilla.org Web Site Structure

Appendix B Where to find documentatation?

-------------------- >8 ----------------------------

Section 0 Premble

0.1. Copyright and disclaimer

Copyright (c) 2002 by the 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 affiliantion with mozilla.org or its finanicial supportors. None of the parties mentioned above accepts any liability in respect of this article or its use.

0.2 Where is the latest vesion of this article?

This article is not archived in any permenant 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 mail to <[EMAIL PROTECTED]>. 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.

0.5 Credits

Due credits of this article are to Daniel Wang (writing and editing) and for the following people for comments and suggestions: Gervase Markham.

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, bugfixes, documentation, localization, feature suggestions, etc.) to the Mozilla project you probably don't want to post here.

See <http://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 welcome word for contributors to the Mozilla open source project.

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 end-user support forums?

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 [EMAIL PROTECTED] 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 committment to walk new comers through the documenation process.

Also, many people who contribute to documentation are also involved in other areas of developement, 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.

Section 2 Netiquettes

2.1 Is top posting allowed?

It depends on the convention in the mailing list. In this forum, the general perference is that reply should follow or interperse with the quoted message.

2.2 Is cross posting allowed?

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).

2.3 Subject matter

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?

You may, but note that this forum is also a mailing list and you should not post large attachments here.

2.6 Can I post HTML messages here?

Unless the circumstance calls for an HTML posting, you should post plain text messages here.

Section 3 Contribute

3.1 Do I have to be a programmer to contribute?

No, anyone can contribute to Mozilla development. Programming is only part of Mozilla developement; many other tasks, including testing, bug tracking, test case writing, usability testing, documentation, translation, and evangelism, do not require expert computer knowledge.

Read <http://mozilla.org/docs/contribute.html> for how to help with documenation. Read <http://mozilla.org/get-involved.html> for how to help with general Mozilla developement.

3.2 I have an idea on improving Mozilla, where can I post my idea?

We use Bugzilla to track all bug reports, including feature requests. If you do not know what Bugzilla is or if you are unfamiliar with it, you should post your idea here. Other people will check your post to see if the request has been filed or not. If your request has not been filed, you should file it at Bugzilla. Ask for assistance should you have any problem filing bug reports.

3.3 I think I have found a bug in Mozilla, what do I do?

Read the previous question.

3.4 How do I make a donation to Mozilla.org?

Information not available. Contribution welcome.


_Part II Documenation_

Section 4 About the Mozilla Documentation Project

4.1 What's the documenation projection site?

The project site lives at http://mozilla.org/docs/mdp

4.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.

4.3 Most of documentations on Mozilla.org site is outdated, why?

To some degree, the fact that Mozilla.org software develope 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.

4.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.

Section 5 Copyright and Legal Issues

5.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>).

5.2 So who owns documentations on mozilla.org?

While this is a mystery, it should be resonably expected that copyrights of content on mozilla.org belong to its respective writer.

5.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...

Section 6 How to Contribute

6.1 Who is doing what?

Documentation status used to be tracked at <http://mozilla.org/docs/mdp/docstat.html>. Unfortunately the page is very out of date (last modified on August 16, 2000).

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.

6.2 What needs to be done?

You may do any documenation you deem relevent to Mozilla and mozilla.org. The topic could be development process, end user manual, source code, open source movement, Web developement with Mozilla, or Mozilla evangelism. There is no priority list for documentation.

The following is a list of open documentation bugs:
http://bugzilla.mozilla.org/buglist.cgi?component=help&component=Miscellaneous&component=Mozilla+Developer&component=User&component=Web+Developer&component=webmaster%40mozilla.org&resolution=---

6.3 How do I modify mozilla.org documentation?

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 relevent 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://mozilla.org/README-cvs.html> and "mozilla.org style guide" <http://mozilla.org/README-style.html>.

6.4 How do I check out Mozilla help files

See http://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.

6.5 How do I check in Mozilla documenation?

You need cvs check-in privilege. For docemenation on the Mozilla Web site, send an e-mail to <[EMAIL PROTECTED]> to find out the procedure. For anything in the source tree, including the Mozilla help files, refer to <http://mozilla.org/hacking/>.

6.6 Where else can I publish my Mozilla documentaion?

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 7 Writing Documentation

7.1 Why isn't DocBook used for documentation format?

Because it would be severe overkill.

7.2 Is there any style manual for mozilla.org documentation?

The "mozilla.org Style Guide" lives at <http://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 documenation.

Also check out "Writing Documentation" <http://moz.zope.org/contribute/writing/walkthrough>

Section 8 Mozilla Help

8.1 How does Mozilla Help system work?

Information not available. Contribution welcome.

Appendix A mozilla.org Web Site Structure

-o www/
 |
 |- mozorg.html             [2002-01-04] Mozilla at a Glance
 |- roadmap.html
 |
 |- owners.html
 |
 |                          -------------------------------------- tools
 |
 |- tools.html
 |- tinderbox.html
 |- bonsai.html
 |
 |                          ---------------------------------- developer
 |
 |- source.html
 |
 o-o hacking/
 |
 o-o build/                 [2002-09-25] build documentation
 | |
 | |- unix.html             [2002-11-12] build linux/unix
 | |- win32.html            [2002-11-22] build Win 32
 | |- mac.html              [2002-06-04] build Mac
 | }-> /ports/fizzilla/     build Mac OS X
 | }-> /ports/os2/          build OS/2
 | }-> /ports/beos/         build BeOS
 | |
 | |- cvs-tag.html          How to create a release tag
 | |- jar-packinag          Jar Packaging 101
 | |- glossary.html         build glossary
 | l- sheriff.html
 |
 |                          ------------------------------------ license
 |
 o- MPL/                    license
 |
 |                          ----------------------------------- projects
 |
 o-o projects/              overview of all projects
 |
 |                          ----------------------------------------- QA
 |
 o-o quality/               overall QA stuff
 | |
 | o-o help/
 |   |
 |   l- bug-form.html
 |
 o-o bugs/                   bugzilla
 |
 |                           ---------------------------------- end user
 |
 o-o releases/               software download
 | |
 | o mozilla1.0.1/           Mozilla 1.0.1 release note
 |
 o-o start/                  end user portals
   |
   o 1.0/                    Mozilla 1.0 & 1.01 end user doc

-o bonsai

-o tinderbox

-o lxr

Appendix B Where to find documentatation?

Documentation portals

mozilla.org FAQs <http://mozilla.org/faq.html>
mozilla.org documenation catalog <http://mozilla.org/catalog/>
HOWTO index <http://mozilla.org/HOWTO/>

Documentation directory (by subject)

Bugzilla, Documentation, FAQs, Hacking, QA, XUL, XPCOM

_Bugzilla_

The Bugzilla Guide Home Page <http://www.trilobyte.net/barnsons/> (2001-08-07) -- based on Bugzilla 2.14

_Documentation_

Writing Documentation <http://moz.zope.org/contribute/writing/walkthrough> -- A guide to writing mozilla.org documenation

_FAQs_

"Mozilla FAQ Engine" <http://www.nic.fi/~jsantal2/mozilla/faq.html>
"Netscape Tips" <http://www.hmetzger.de/etips6.html>

_Hacking_

"Getting CVS Write Access to Mozilla" <http://mozilla.org/hacking/getting-cvs-write-access.html> [cvs, review process, patch]

"Source Code via CVS" <http://mozilla.org/cvs.html> (2002-11-26) [cvs]

"Comparing and Merging Files" <http://www.gnu.org/manual/diffutils-2.8/diff.html> [diff, patch] -- user manual to GNU diff utilities

"mozilla `super-review'" <http://mozilla.org/hacking/reviewers.html> [review process]

"C++ portability guide" <http://mozilla.org/hacking/portable-cpp.html>

"NsArrays" <http://mozilla.freezope.org/docnotes/NsArrays>

"GetInterface" <http://mozilla.freezope.org/docnotes/GetInterface>

"Open Source Development With CVS" <http://cvsbook.red-bean.com/cvsbook.html> [cvs]

Boswell, David et. al. _Creating Applications with Mozilla_ <http://www.oreilly.com/catalog/mozilla/> (2002)

_XUL_

XULPlanet <http://www.xulplanet.com/>

_XPCOM_

XPInstall API Reference <http://developer.netscape.com/docs/manuals/xpinstall/xpinstal.html> -- note: component not completely implemented

blah

Documentation FAQ

Reply via email to