On Thu, Jun 15, 2017 at 1:04 PM, Andrew Halberstadt < ahalberst...@mozilla.com> wrote:
> +1 to preferring in-tree docs. > +1 to this from me as well. Wish it was easier to contribute, but the in-tree docs are the best trade-off we have right now. Nick > > 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/opend >> esign/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_g >> uide/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-contributio >> n-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 > >
_______________________________________________ dev-builds mailing list dev-builds@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-builds
