471144 - [Tracking]Remove documentation from mozilla-central, and move to appropriate place(s)

Status: RESOLVED WONTFIX

(Core Graveyard :: Tracking, defect)

Description

[Tyler Downer [He/Him]]

Throughout the entire mozilla-central tree, there are various html readmes, docs, etc. that have a few problems (some more important than others):
1. They are difficult to find, unless you know right where they are, or search.(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 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)
4. They are often not well formatted in the markup they use. (Nice to have)
5. They clutter the tree somewhat. (nice to have)

As said in bug 467698, and bug 467605, some, if not all of these docs could be moved to either devmo, wmo, qmo, mo, or some other online site. Some are already there, and their identical text is still in the tree.
There are several advantages to moving these docs online:
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 1, 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)
5. They would clean up the tree, making it a bit smaller and easier to use. (addresses issue 5)

Now, those who are used to the current location of these documents would likely be disoriented a bit, if they are using them. So a good bet may be to place a simple text document in the root folder of mozilla-central (docs.txt), that will point users to developer.mozilla.org/en/Mozilla_Source_Code_Directory_Structure (or https://developer.mozilla.org/en/Source_code_directories_overview). That page has almost every folder in mozilla-central documented, and links from there to their project page(s). It would have to advantage of driving users to learn more about something before they use it, and the new documentation would be linked from the project pages (or directly on them).

Comment 1

[Tyler Downer [He/Him]]

Creating a wiki. I will post some lists of the docs that need moving, and potential places for them to go to.

Comment 2

[Tyler Downer [He/Him]]

There you go Brenden

Comment 3

[Tyler Downer [He/Him]]

If anyone wants to finish this, feel free to use my patches and bugs.

Comment 4

[Benjamin Smedberg]

We have real in-tree docs with automation to gecko.readthedocs.org, and we're actively using that instead of wikimo/MDN for focused technical/code-level docs.