Closed Bug 1606026 Opened 8 months ago Closed 7 months ago

Hard to find documentation "entry point"

Categories

(Firefox Build System :: Generated Documentation, task)

task
Not set
normal

Tracking

(firefox74 fixed)

RESOLVED FIXED
mozilla74
Tracking Status
firefox74 --- fixed

People

(Reporter: glasserc, Assigned: glasserc)

References

Details

Attachments

(4 files)

The current location for the documentation "front page" is in tools/docs. In issues such as bug 1605742, additional "top-level" documentation about the repository and workflow itself is being added to this directory as well. This location is not especially obvious for a new contributor and does not correspond well to the nature of the documentation as "top-level" or corresponding to the repository.

I'd like to propose the following structure for documentation:

  • docs/ -- main entry point for docs. This should correspond to the "Mozilla Source Tree Documentation" page and the corresponding table of contents. I also think some related configuration and metadata could go here. In other words, this should contain all the files that are in tools/docs (but not subdirectories) today.
  • docs/contributing/ -- a section in the docs dedicated to the knowledge necessary to use the repository itself, including workflow. This would correspond to everything in tools/docs/docs/ today, plus stuff from MDN.

The only remaining thing in tools/docs would be tools/docs/moztreedocs, which I would propose to move into python/ alongside python/mozbuild or even inside python/mozbuild alongside python/mozbuild/mozbuild/sphinx.py.

I don't have a strong opinion on this.
I am not convinced by the complexity of finding the right file. A simple ripgrep or searchfox find quickly the relevant files.
Andrew, wdyt?

Flags: needinfo?(ahal)
Assignee: nobody → eglassercamp
Status: NEW → ASSIGNED
  • Rename the existing collection of one-liners to "phrasebook", as
    this gives a better summary of the document.

I took the liberty of preparing a patch for this while everything was fresh in my mind, although I completely understand if this gets closed as WONTFIX.

Thinking more about it, I came to the conclusion that the documentation currently under tools/docs/docs is mostly about the doc tooling -- I agree that it's fine where it is. However, I do think that general "how to contribute to Firefox" documentation should not be buried under tools.

Thanks for moving the docs around.

I do think that general "how to contribute to Firefox" documentation should not be buried under tools.

Its there for only sometime, once we are done with all the migration of the docs inside the firefox , we planned for re-arranging everything in well manner

I think this proposal makes a lot of sense. I'd suggest we have:

  1. docs
  2. tools/moztreedocs
  3. tools/moztreedocs/docs

Where 1) would contain the docs that apply to the tree in general, 2) would have the mach_command.py file + what is currently in tools/docs/moztreedocs and 3) would contain the docs for writing/generating docs.

I'd mildly prefer we keep it under tools as opposed to python. The latter is usually more for library type things that get imported by Python modules elsewhere. The former tends to contain the actual cli tools that developers use.

Flags: needinfo?(ahal)
Attachment #9117944 - Attachment description: Bug 1606026: Move docs to toplevel docs/ directory → Bug 1606026: move tools/docs code to tools/moztreedocs
Attachment #9117945 - Attachment description: Bug 1606026: Move existing documentation under docs/contributing → Bug 1606026: Move existing documentation into new locations
Duplicate of this bug: 1607044
Pushed by eglassercamp@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/8d2a9c2c512d
move tools/docs code to tools/moztreedocs r=sylvestre
https://hg.mozilla.org/integration/autoland/rev/f7974eae3d64
Move documentation entry point to docs/ r=sylvestre
https://hg.mozilla.org/integration/autoland/rev/d03b5479fab3
Move existing documentation into new locations r=sylvestre
Status: ASSIGNED → RESOLVED
Closed: 7 months ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla74
Regressions: 1607355
Pushed by sledru@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/e0cb511a73db
no bug - follow up of Bug 1606026 - Add docs/ to the list of dirs r=glasserc

This broke lot of urls of the existing docs as the links and needs to update the links of the files mentioned in docs as well.

Which links are the ones that broke? I grepped tools/docs in the source repository and didn't see anything else that was affected, but there could be stuff outside this repository. If necessary, we could put in redirects. If we can instead fix the links so that they point to the correct locations, that would be better, but it requires knowing which pages have the links on them.

Docs for managing docs and how to contribute docs needs to be redirects as we shared these docs around twitter and IRC , also few minor nits to the config.yml needs to be set in managing docs

(In reply to Ethan Glasser-Camp (:glasserc) from comment #15)

Which links are the ones that broke?

Example: https://firefox-source-docs.mozilla.org/tools/docs/contribute/how_to_contribute_firefox.html

Regressions: 1616969
You need to log in before you can comment on or make changes to this bug.