1513821 - [meta] Generated documentation needs a better structure

Status: NEW

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[Mark Banner (:standard8)]

Looking at https://firefox-source-docs.mozilla.org/ we have a really confusing structure.

It is not in alphabetical order, and it isn't organised by the normal structures that we use, e.g. "Firefox" (or "browser"), "Firefox for Android" (or "fennec"), "Toolkit", "Testing" etc.

This makes it really hard to look for something just by looking at the contents.

For example, here's some top-level items:

- tabbrowser
- Firefox
- Form Autofill
- Web Payments UI
- Installer

The above should arguably be all under "Firefox".

There's also things like:

- Crash Manager
- WebExtensions API Development
- Shield Recipe Client
- Telemetry
- URL Classifier
- Toolkit Widgets
- Crash Reporter

and more, that should be structured under "Toolkit" (or some appropriate name).

I believe one of the problems is that for any directory where docs are in the source tree, we create a new top-level documentation item.

I think we should be able to have some sort of sub-item specification, so that the documentation could be at the top-level, or it could be as a sub-item of something else in the documentation tree.

Comment 1

[Andrew Halberstadt [:ahal]]

I think this is more or less the same as bug 1484691 :)

But since that bug is very technical and doesn't have an easy to understand summary, I propose we use that bug to implement the *ability* to nest doc trees, and then use this bug to *actually move* the docs around.

Comment 2

[Emma Humphries ☕️🎸🧞‍♀️✨ (she/they) [:emceeaich] (Pacific Time) use needinfo]

Per conversation with :kmoir, I'm going through untriaged bugs in her components and marking the ones which look to be enhancements/tasks with the enhancement severity to get them out of the triage queue.

If this incorrect, please remove the tag.

Comment 3

[Mark Banner (:standard8)]

I think this is a bug rather than an enhancement - as a result of this, our docs are in a mess and can't easily be sorted out.

Comment 4

[Andrew Halberstadt [:ahal]]

Since this is now technically possible, we only have the hard part of re-writing everything. I don't think it's feasible that we'll do the entire thing in one go (nor would that be a good idea). I think we'll need module owners and peers in their respective domains to step up and get the ball rolling one section at a time.

I propose we turn this into a meta bug and use it to come up with the top-level section names that should appear in the root sidebar. Then we can file blocking bugs for each top-level section (preferably in the component that the section is most relevant to) and try to find volunteers to tackle them.

It might also be a good idea to block on bug 1527363 as a reorganization of this scale will break pretty much every external link to firefox-source-docs. There are ways we can manually set up redirects (using meta refresh) in the meantime though if anyone is motivated enough to get started on this.

Comment 5

[Andrew Halberstadt [:ahal]]

Just a general comment...

So far our doc trees tend to directly map to their file-system structure in mozilla-central. My personal opinion is that we should try and move away from this (or at least think about it before blindly cargo-culting from another SPHINX_TREES definition), and instead organize them in whatever manner makes the most sense for each individual doc tree.

I noticed that most docs fall into one of two broad categories:

1. User docs. These are instructions on how to contribute, how to run things, how to perform various tasks, etc.
2. Technical docs. These are deeply technical documents for various components explaining design decisions, interactions with other systems, describing how things work, etc.

I'm no technical writer, so I'd love to get input from someone who knows what they are doing.. but I believe it would be good to separate these two types of docs into broad landing pages. E.g,

1. A "Mozilla Central User Guide" landing page that contains all the docs related to how to contribute to mozilla-central. Stuff like running linters, pushing to try, running builds, running tests, vcs etc. We could try and mimic the MDN contribution docs and make a sort of guided tutorial that walks through the whole process.

2. A "Gecko" (or maybe "Firefox") landing page that houses all the more technical things that only people working on a given component will likely care about. Might be worth having separate top-level pages for frontend and gecko things here (not sure).

This means that instead of:

SPHINX_TREES["browser"] = "docs"

we would use:

SPHINX_TREES["/gecko/browser"] = "docs"

Instead of:

SPHINX_TREES["tools/lint"] = "docs"

we would use:

SPHINX_TREES["/user-guide/lint"] = "docs"

Anyway, I'm not planning to work on this anytime soon or anything. Just wanted to put my thoughts on this in writing somewhere.

Comment 6

[Mike Hoye [:mhoye]]

Taking this bug.

Comment 7

[Andrew Halberstadt [:ahal]]

Hey Mike, I know you're busy, so I'm mainly asking out of curiosity rather than any expectation of action..

Do you have any plans for moving this forward? Just wondering if there's going to be some sort of process/committee to get our docs organized and if so if there's a (very) rough timeline.

Comment 9

[Mike Hoye [:mhoye]]

Leaving the NI open - I am starting to dig into this right now, and will keep this bug apprised of my progress.

Comment 10

[Andrew Halberstadt [:ahal]]

Just a general fyi to the people CC'ed here. Sylvestre put up a patch in bug 1593084 that re-organizes the main page a bit. I'm inclined to accept it because it's an obvious incremental improvement over the status quo, though it's likely not going to represent the final way we decide to organize the docs.

But figured I'd mention it here in case anyone wants to provide feedback:
https://phabricator.services.mozilla.com/D51306

There's a screenshot attached in the bug if you want to avoid building it locally.

Comment 11

[Sylvestre Ledru [:Sylvestre]]

And it is live:
https://firefox-source-docs.mozilla.org/
I think we should just replicate this structure in the nav-bar

Comment 12

[Mike Hoye [:mhoye]]

Lots of updates to this have happened recently, including moving a bunch of stuff over from MDN.

I'll keep working on it.

Comment 13

[Andrew Halberstadt [:ahal]]

Our GSoC intern Emil created a crawler to help migrate docs from MDN:
https://github.com/Emilfs/mdn-crawler

Some results here:
https://drive.google.com/drive/folders/1uTVq6-Gpdu9nhDmT_0JoBh5Z4m5uH5Ft

It's going to take a fair amount of work to figure out what we want to import and where. Maybe we should resolve this bug (the structure looks much better now) and create a new meta bug to tackle the rest of the migration?

Comment 14

[Andrew Halberstadt [:ahal]]

Apparently said meta bug already exists (bug 1617963). I'll leave it up to mhoye whether this one is fixed enough or not then.

Comment 15

[BugBot [:suhaib / :marco/ :calixte]]

The bug assignee is inactive on Bugzilla, so the assignee is being reset.