Builds docs on MDN

--001a114583b2b581b6055204dbdf
Content-Type: text/plain; charset="UTF-8"

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.

--001a114583b2b581b6055204dbdf
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>MDN is pivoting hard to focus on web docs: <a href=3D=
"https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/">https://bl=
og.mozilla.org/opendesign/future-mdn-focus-web-docs/</a></div><div><br></di=
v><div>MDN will actively start de-emphasizing docs that aren&#39;t related =
to the web. You can already see this on things like search results: <a href=
=3D"https://developer.mozilla.org/en-US/search?q=3Dfirefox%20build">https:/=
/developer.mozilla.org/en-US/search?q=3Dfirefox%20build</a>. Note how the &=
quot;Firefox&quot; topic isn&#39;t searched by default. I also heard MDN ma=
y start excluding non-web docs from search engine indexing. If they do this=
, search results for e.g. &quot;contribute to Firefox&quot; will likely go =
nowhere useful.<br></div><div><br></div><div>There are a ton of build syste=
m (and general Firefox development docs) on MDN. e.g. <a href=3D"https://de=
veloper.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions">=
https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Inst=
ructions</a>.</div><div><br></div><div>We already had fragmented Firefox bu=
ild docs. We have things scattered between MDN, <a href=3D"http://wiki.mozi=
lla.org">wiki.mozilla.org</a>, in-tree Sphinx docs, and years of mailing li=
st and blog posts (which sadly are the sole source of some useful info). Wi=
th 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 doc=
s off MDN. Or at the very least we shouldn&#39;t continue to invest much ef=
fort in the MDN docs.</div><div><br></div><div>Personally, I&#39;d like to =
see us move towards the in-tree docs. Those are currently hosted at <a href=
=3D"https://gecko.readthedocs.org/">https://gecko.readthedocs.org/</a> (alt=
hough that&#39;s been broken for a few weeks and before that it was only re=
liable ~50% of the time because our scale breaks RTD). We can certainly imp=
rove the robustness. Possibly by hosting ourselves if we need to. However, =
the in-tree docs aren&#39;t a wiki, so the barrier to change is higher - bo=
th in terms of process to edit and the knowledge required to use ReST + Sph=
inx. I&#39;ve explored some of this in more detail at <a href=3D"https://gr=
egoryszorc.com/blog/2015/01/09/firefox-contribution-process-debt/">https://=
gregoryszorc.com/blog/2015/01/09/firefox-contribution-process-debt/</a>. I =
wholeheartedly agree that wikis are more user friendly. However, I also fee=
l 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 vers=
ion 55 via source control), link verification, and a code review process so=
 build peers can prevent bad docs before they are seen by others.<br></div>=
<div><br></div><div>I wanted to start a thread to see what people think we =
should do. And to be clear, I&#39;m not yet proposing that we incur a bunch=
 of work to move things. But we probably should figure out where are docs e=
fforts should be invested moving forward.<br></div></div>

--001a114583b2b581b6055204dbdf--
0
Gregory
6/15/2017 7:41:02 PM
mozilla.dev.builds 1675 articles. 0 followers. Post Follow

0 Replies
21 Views

Similar Articles

[PageSpeed] 33

Reply: