n.p.m.documentation FAQ ?

[Daniel Wang]

about time n.p.m.documenation document itself?

           Frequently Asked Questions (FAQ)
                      for
     mozilla.org Documentation (d11n) Mailing List

                    Daniel Wang

                    (2002-12-01)

 Table of Contents
 1 About this Mailng List
     1.1 Is there an FAQ for this mailing list?
     1.2 What's this mailing list for?
     1.3 What are the rules of posting?
     1.4 Many people have offered to help with documentation in
         this forum, what happened to them?
     1.5 So how do I get help with my documentation?
 2 About the Mozilla Documentation Project
     2.1 What's the documenatio projection site?
     2.2 How is the Mozilla Documentation Project organized?
     2.3 Most of documentations on Mozilla.org site is outdated, why?
     2.4 Is there any plan to update the documentation?
 3 Copyright and Legal Issues
     3.1 What license is Mozilla.org documentation licensed under?
     3.2 So who owns documentations on mozilla.org?
     3.3 How about the Open Publication License?
 4 How to Contribute
     4.1 Who is doing what?
     4.2 What needs to be done?
     4.3 How do I modify mozilla.org documentation?
     4.4 How do I check out Mozilla help files
     4.5 How do I check in Mozilla help files?
     4.6 Where else can I publish my Mozilla documentaion?
 5 Writing Documentation
     5.1 Why isn't OpenDoc used for documentation format?
     5.2 Is there any style manual for mozilla.org documentation?

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

Section 1 About this Mailing List

1.1 Is there an FAQ for this newsgroup?

No, but hopefully this document will evolve to be one.

1.2 What's this mailing list for?

For documentation dicussion, of course.

1.3 What are the rules of posting?

see <http://mozilla.org/community.html#ground-rules>

1.4 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 (d11n) 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 d11n 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.5 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 About the Mozilla Documentation Project

2.1 What's the documenation projection site?

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

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

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

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

3.2 So who owns documentations on mozilla.org?

mozilla.org automatically inserts the line "Copyright � 1998-2002 The
Mozilla Organization." to the end of every mozilla.org document, so
practically mozilla.org owns every documentation checked in by contributors.

Some Mozilla.org files do not have the copyright line, so there may be
special code to override the auto-insertion. Unfortunately I don't know
what it is.

3.3 How about the Open Publication License?

Good suggestion. If you want your d11n contribution to be licensed under Open Publication License <http://www.opencontent.org/openpub/>, you should put a license note in your contribution.

Section 4 How to Contribute

4.1 Who is doing what?

Documentation (d11n) 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 d11n 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.

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

4.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 and a .diff file. If you have mozilla-org cvs access privilege, you may check in the file directly (be sure that you make a prior announcement about 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.

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

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

4.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 site is more "open" than mozilla.org.

Of course you can publish your file elsewhere and have Mozilla Web site link to it :)

Section 5 Writing Documentation

5.1 Why isn't OpenDoc used for documentation format?

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

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