+1 to preferring in-tree docs. If we're going to be adding a ton of new docs though, I think it would be worth exploring a different sphinx theme. I find the toctree in the side bar of the default rtd theme is already looking cluttered and getting difficult to navigate. I imagine with an order of magnitude more content, it will be more confusing than helpful.
On Thu, Jun 15, 2017 at 3:41 PM, Gregory Szorc <g...@mozilla.com> wrote: > MDN is pivoting hard to focus on web docs: https://blog.mozilla.org/ > opendesign/future-mdn-focus-web-docs/ > > MDN will actively start de-emphasizing docs that aren't related to the > web. You can already see this on things like search results: > https://developer.mozilla.org/en-US/search?q=firefox%20build. Note how > the "Firefox" topic isn't searched by default. I also heard MDN may start > excluding non-web docs from search engine indexing. If they do this, search > results for e.g. "contribute to Firefox" will likely go nowhere useful. > > There are a ton of build system (and general Firefox development docs) on > MDN. e.g. https://developer.mozilla.org/en-US/docs/Mozilla/Developer_ > guide/Build_Instructions. > > We already had fragmented Firefox build docs. We have things scattered > between MDN, wiki.mozilla.org, in-tree Sphinx docs, and years of mailing > list and blog posts (which sadly are the sole source of some useful info). > With MDN pivoting towards the web and being hostile to non-web docs, I > think the writing is clear that we should be moving Firefox > build/development docs off MDN. Or at the very least we shouldn't continue > to invest much effort in the MDN docs. > > Personally, I'd like to see us move towards the in-tree docs. Those are > currently hosted at https://gecko.readthedocs.org/ (although that's been > broken for a few weeks and before that it was only reliable ~50% of the > time because our scale breaks RTD). We can certainly improve the > robustness. Possibly by hosting ourselves if we need to. However, the > in-tree docs aren't a wiki, so the barrier to change is higher - both in > terms of process to edit and the knowledge required to use ReST + Sphinx. > I've explored some of this in more detail at > https://gregoryszorc.com/blog/2015/01/09/firefox- > contribution-process-debt/. I wholeheartedly agree that wikis are more > user friendly. However, I also feel like the in-tree docs get us nice > things like versioning (someone wanting to build Firefox 55 2 years from > now will have access to the docs for version 55 via source control), link > verification, and a code review process so build peers can prevent bad docs > before they are seen by others. > > I wanted to start a thread to see what people think we should do. And to > be clear, I'm not yet proposing that we incur a bunch of work to move > things. But we probably should figure out where are docs efforts should be > invested moving forward. > > _______________________________________________ > dev-builds mailing list > dev-builds@lists.mozilla.org > https://lists.mozilla.org/listinfo/dev-builds > >
_______________________________________________ dev-builds mailing list dev-builds@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-builds
