Closed Bug 471144 Opened 13 years ago Closed 5 years ago

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

Categories

(Core Graveyard :: Tracking, defect)

defect
Not set
minor

Tracking

(Not tracked)

RESOLVED WONTFIX

People

(Reporter: tdowner, Unassigned)

References

(Depends on 2 open bugs, )

Details

(Keywords: meta)

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).
Summary: Remove documentation from mozilla-central, and move to devmo, or other appropriate place(s) → [Tracking]Remove documentation from mozilla-central, and move to appropriate place(s)
Depends on: 471146
Depends on: 471148
Depends on: 471154
Depends on: 471215
Creating a wiki. I will post some lists of the docs that need moving, and potential places for them to go to.
Depends on: 471480
Depends on: 471588
There you go Brenden
Depends on: 471930
Assignee: nobody → tyler
Status: NEW → ASSIGNED
Depends on: 473466
Keywords: meta
If anyone wants to finish this, feel free to use my patches and bugs.
Status: ASSIGNED → NEW
Assignee: tdowner → nobody
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.
Status: NEW → RESOLVED
Closed: 5 years ago
Resolution: --- → WONTFIX
Product: Core → Core Graveyard
You need to log in before you can comment on or make changes to this bug.