Hard to find documentation "entry point"
Categories
(Developer Infrastructure :: Source Documentation, task)
Tracking
(firefox74 fixed)
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 intools/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 intools/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•5 years ago
|
||
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?
Assignee | ||
Comment 2•5 years ago
|
||
Updated•5 years ago
|
Assignee | ||
Comment 3•5 years ago
|
||
- Rename the existing collection of one-liners to "phrasebook", as
this gives a better summary of the document.
Assignee | ||
Comment 4•5 years ago
|
||
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•5 years ago
|
||
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•5 years ago
|
||
I think this proposal makes a lot of sense. I'd suggest we have:
- docs
- tools/moztreedocs
- 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.
Updated•5 years ago
|
Assignee | ||
Comment 7•5 years ago
|
||
Updated•5 years ago
|
Comment 10•5 years ago
|
||
bugherder |
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•5 years ago
|
||
Comment 12•5 years ago
|
||
Comment 13•5 years ago
|
||
bugherder |
Comment 14•5 years ago
|
||
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.
Assignee | ||
Comment 15•5 years ago
|
||
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•5 years ago
|
||
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•5 years ago
|
||
(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
Updated•2 years ago
|
Description
•