FWIW most of my contributions to the documentation hosted on MDN were in
the form of casual edits here and there to pages, mostly in the form of
me noticing something wrong in some documentation and quickly editing
the wiki to fix it. The editing process of the MDN wiki was (well,
still is!) exceptionally good at this workflow, so it is extremely sad
to not be able to continue to use it going forward.
For those types of casual contributions, I certainly feel like the
barrier for filing bugs, creating a patch, figuring out how to use
readthedocs infrastructure, getting reviews, etc. isn't really worth it,
since I'm comparing it to a workflow that used to take a few seconds, so
a switch to a workflow based on in-tree docs would drive someone like me
away. But maybe those types of casual contributions aren't worth
optimizing worth here.
(Also, maybe it's just me, but even though I have done tons of code
archeology, in practice I don't recall having much if any at all of
documentation archeology personally so part of the reason why I'm
reluctant in spending the effort to switch to a workflow based on
in-tree documentation is because I feel like I haven't yet seen how it
benefits me!)
My CDN$0.02,
Ehsan
On 06/15/2017 03:41 PM, Gregory Szorc 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 <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-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
