Fwd: Builds docs on MDN

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Fwd: Builds docs on MDN

ISHIKAWA,chiaki
Hi,

Based on the following message on dev-builds, should't we be concerned
about TB's docs which are already sparse IMHO?

Of course, the concern must be evaluated in the framework of the TB
development in the next few years when TB will be based on a different
core (?), and in different  build framework(?) and different repository.

So contributing to dev-builds may be futile, but at least we should
salvage updated corrected docs from MSDN and keep them alive in an
easily accessibl (and editable [under accountability? this is
difficult.]  place.

I agree with in-source/in-tree docs approach in the original post, but
that is not the main point of my post here.

I have not heard of MDN's policy change, if any,
and we should do something about it if obtaining the TB documents or
contribution is made difficult
[well, I am not saying the documents are satisfactory already, but
making them harder to find is insane in terms of enhancing TB
development community which is already too small.]

-------- Forwarded Message --------
Subject: Builds docs on MDN
Date: Thu, 15 Jun 2017 12:41:02 -0700
From: Gregory Szorc <[hidden email]>
To: dev-builds <[hidden email]>
CC: Mike Hoye <[hidden email]>



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 <http://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-apps-thunderbird mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-thunderbird

=?UTF-8?B?5re75LuY44Oh44OD44K744O844K46YOo?= (208 bytes) Download Attachment