1606026 - Hard to find documentation "entry point"

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, task)

Description

[Ethan Glasser-Camp (:glasserc)]

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.

Comment 1

[Sylvestre Ledru [:Sylvestre]]

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?

Comment 2

[Ethan Glasser-Camp (:glasserc)]

Attachment: Bug 1606026: move tools/docs code to tools/moztreedocs

Comment 3

[Ethan Glasser-Camp (:glasserc)]

Attachment: Bug 1606026: Move existing documentation into new locations

• Rename the existing collection of one-liners to "phrasebook", as
  this gives a better summary of the document.

Comment 4

[Ethan Glasser-Camp (:glasserc)]

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.

Comment 5

[Shivam Singhal [ :championshuttler ]]

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

Comment 6

[Andrew Halberstadt [:ahal]]

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.

Comment 7

[Ethan Glasser-Camp (:glasserc)]

Attachment: Bug 1606026: Move documentation entry point to docs/

Comment 9

[Pulsebot]

Pushed by [e-mail]:
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

Comment 10

[Noemi Erli[:noemi_erli]]

https://hg.mozilla.org/mozilla-central/rev/8d2a9c2c512d
https://hg.mozilla.org/mozilla-central/rev/f7974eae3d64
https://hg.mozilla.org/mozilla-central/rev/d03b5479fab3

Comment 11

[Sylvestre Ledru [:Sylvestre]]

Attachment: no bug - follow up of Bug 1606026 - Add docs/ to the list of dirs r?glasserc

Comment 12

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/e0cb511a73db
no bug - follow up of Bug 1606026 - Add docs/ to the list of dirs r=glasserc

Comment 13

[Raul Gurzau (:RaulG)]

https://hg.mozilla.org/mozilla-central/rev/e0cb511a73db

Comment 14

[Shivam Singhal [ :championshuttler ]]

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.

Comment 15

[Ethan Glasser-Camp (:glasserc)]

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.

Comment 16

[Shivam Singhal [ :championshuttler ]]

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

Comment 17

[Sylvestre Ledru [:Sylvestre]]

(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