Move mozilla-central docs to appropriate websites

Owners

Tyler Downer <tyler.downer@gmail.com>

Status

Feature tracking bug

• bug 471144

This feature would be nice to have by the release of Mozilla 2. Because of the massive rewrites, the removal of this documentation would probably be acceptable before Mozilla 2 is released. Mozilla 2 goal 3: "Simplify the Mozilla codebase to make it smaller, faster, and easier to approach and maintain." Though meaning the actual working code, it can apply to the whole mozilla-central.

Overview and Motivations

Problems with the Current location of Docs

1 They are difficult to maintain (some have not been updated for years, and are by their own admission, out of date, due to referenced bugs). Changing them requires a patch to be checked in the tree. (pretty important)

2 They are nearly impossible to view if you do not have access to the tree (except through mxr, etc.) (Important)

3 They are difficult to find, unless you know right where they are, or search.(Important)

4 They are often not well formatted in the markup they use. (Nice to have)

5 They clutter the tree somewhat. (Nice to have)

Advantages of moving to a Mozilla.org site

1 It will be much easier to find them, a simple google search, or mozilla search, will most likely find them. That is the place most developers looking for help will probably look. (Addresses issues 4, 2)

2 They would be much easier to edit, update and maintain. A simple website update would instantly bring the new content to the world's fingertips. Updated content would also make them more useful to developers.(addresses issue 3)

3 The markup used by mozilla sites is usually better than much of the markup currently in use. (addresses issue 4)

4 They would clean up the tree, making it a bit smaller and easier to use. (addresses issue 5)

Risks and Assumptions

Problems with the Current location of Docs

1. They are difficult to maintain (some have not been updated for years, and are by their own admission, out of date, due to referenced bugs). Changing them requires a patch to be checked in the tree. (pretty important)

2. They are nearly impossible to view if you do not have access to the tree (except through mxr, etc.) (Important)

3. They are difficult to find, unless you know right where they are, or search.(Important)

4. They are often not well formatted in the markup they use. (Nice to have)

5. They clutter the tree somewhat. (Nice to have)

Advantages of moving to a Mozilla.org site

1. It will be much easier to find them, a simple google search, or mozilla search, will most likely find them. That is the place most developers looking for help will probably look. (Addresses issues 4, 2)

2. They would be much easier to edit, update and maintain. A simple website update would instantly bring the new content to the world's fingertips. Updated content would also make them more useful to developers.(addresses issue 3)

3. The markup used by mozilla sites is usually better than much of the markup currently in use. (addresses issue 1)

4. They would clean up the tree, making it a bit smaller and easier to use. (addresses issue 5)

Disadvantages of moving

1 Current users may be disoriented, and not sure where the docs are now located. One solution is to place a not in the readme in mozilla-central root, pointing to https://developer.mozilla.org/en/Mozilla_Source_Code_Directory_Structure, which points to every bit of documentation (or almost).

Schedule and Milestones

A rough schedule is below (tentative)

• Sept 2009: Complete a list of all docs that need to be removed, and file bugs for them.
• Nov 2009: Receive approval for bugs and check them in. As docs are removed, place identical content on the chosen destination.
• September 2009: Finish cleanup Review code base and new online documents for accuracy.

Why Mozilla 2?

The question may occur, why am I shooting for Mozilla 2, instead of 1.9.2?

• Mozilla 1.9.2 is already in active development. In the time required for the invasive changes and review for total removal of the documentation, as well as adding it in sync to the chosen destination, 1.9.2 will be much further advanced in it's development. While some of these docs may be removed, the possibility exists that not all will be. In order to save time for more essential tasks needed for 1.9.2, this is being put some time out in the future. It is possible that in the near future it will become apparent that this can make the 1.9.2 release, and the wiki will be updated.Some of these docs will be removed in 1.9.2, but the majority will probably be gone in 1.9.3.