Moving build docs off MDN and into M-C

Firefox Development
#1

Hi, everyone -

I’m planning to move a bunch of documentation about how to build Firefox off MDN and into mozilla-central, the source repository where Firefox lives, so that it’s easier to keep our documentation in sync with everything actually being documented.

The end result of that (I expect) will be that https://firefox-source-docs.mozilla.org/ will become the place all this stuff will be most easily visible.

I considered it putting it on Wikimo, but I think that in this case the most important thing is to reduce barriers to maintenance, as opposed to barriers to editing. That is to say, to make sure that documentation can be maintained in the same editor, via the same toolchain as the code or process being documented, ideally in the same commit or set of commits.

Does this seem like a reasonable approach, and does anyone have any concerns about this process?

Thanks,

  • mhoye
1 Like
#2

I think this is a reasonable approach. Can we make sure that the MDN pages redirect to the new URL once all is set up?

#3

Gecko builds aren’t the only ones that are on MDN. I’m sure that the NSS team would be happy to accept assistance in this regard, but it’s a pretty big lift.

1 Like
#4

Centering MDN around documentation for the open web platform would be a big win.

Ultimately, moving useful content to firefox-source-docs.m.o is the responsibility of module owners, but there is also a lot of outdated content with no clear owners on MDN that it would be good to just get rid of.

Documentation for all the modules I own has already moved out of MDN, and with Markdown enabled in Sphinx (thanks @maja_zf!) it is not nearly as painful as you might think.

Tangentially related is my proposal on dev-platform to ease review requirements for documentation updates in central.

#5

One thing that has been on my mind is that MDN has a lot of (albeit slightly outdated) XPCOM/XPIDL documentation that it would be useful to preserve.

It would be really quite good if someone volunteered to write some code for auto-generating the Gecko-internal XPIDLs on firefox-source-docs. There is some prior art in this area for JS autodocs.

1 Like
#6

I concur with the strategy to prioritize ease of maintenance over ease of editing. This approach is also consistent with the industry trend to treat docs like code.

Can we make sure that the MDN pages redirect to the new URL once all is set up?

Just be sure to work with the MDN team on that, so they can schedule in any work on their side.

1 Like