Re: Reviews for in-tree documentation (was: Builds docs on MDN)

I think we should question the assumption that writing source-code-level documentation is a good activity for newcomers to the codebase. Documentation is usually best written by someone with a deep understanding of what is being documented, not by someone new to the project. And this

Re: Reviews for in-tree documentation (was: Builds docs on MDN)

Also sprach Sylvestre Ledru: By the way, do we know how many mdn contributions are made on these pages by people who are not regular Firefox developers? A push in-tree requires permissions, which isn't a small barrier, might impact that (not mentioning the size of the repo). If this is only a

Re: Reviews for in-tree documentation (was: Builds docs on MDN)

ea I would like to know what steps > to take next to make that policy. > I am planning on implementing this. I'll probably track it off bug 1395763 somewhere. The timetable with Phabricator may hold up aspects of it a bit. > > -- >8 -- > From: Boris Zbarsky <bzbar...@mit.ed

Re: Builds docs on MDN

On 06/22/2017 12:11 AM, ISHIKAWA,chiaki wrote: (I am posting a response to Ehsan's message which somehow was garbled and he kindly corrected in a personal exchange.) On 2017/06/22 6:10, Ehsan Akhgari wrote: Oops, not sure how that happened, sorry about that! But that formatting corruption

Re: Builds docs on MDN

(I am posting a response to Ehsan's message which somehow was garbled and he kindly corrected in a personal exchange.) On 2017/06/22 6:10, Ehsan Akhgari wrote: Oops, not sure how that happened, sorry about that! But that formatting corruption seemed to have happened in the text I quoted.

Re: Builds docs on MDN

On Fri, Jun 16, 2017 at 7:40 AM, Boris Zbarsky wrote: > On 6/16/17 9:33 AM, Ehsan Akhgari wrote: > >> 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 >> >

Re: Builds docs on MDN

There are multiple kinds of docs. One group that I've done a lot of work on is the collection of pages under https://developer.mozilla.org/en-US/docs/Mozilla/Performance. I'm not sure if in-tree would be better for those or not, but they're certainly in a different category to API docs, for

Re: Builds docs on MDN

On 2017/06/21 2:19, Ehsan Akhgari wrote: On 06/20/2017 12:55 PM, Benjamin Smedberg wrote: On Tue, Jun 20, 2017 at 12:40 PM, Ehsan Akhgari > wrote: On 06/20/2017 11:21 AM, Benjamin Smedberg wrote: Coming in late to this

Re: Builds docs on MDN

On 06/20/2017 12:55 PM, Benjamin Smedberg wrote: On Tue, Jun 20, 2017 at 12:40 PM, Ehsan Akhgari > wrote: On 06/20/2017 11:21 AM, Benjamin Smedberg wrote: Coming in late to this thread, but I'd like to strongly

Re: Builds docs on MDN

On Tue, Jun 20, 2017 at 12:40 PM, Ehsan Akhgari wrote: > On 06/20/2017 11:21 AM, Benjamin Smedberg wrote: > >> Coming in late to this thread, but I'd like to strongly support moving >> our Mozilla internals documentation in the tree. >> > It seems that the rest of your

Re: Builds docs on MDN

Coming in late to this thread, but I'd like to strongly support moving our Mozilla internals documentation in the tree. The fundamental problem with our current doc situation is not that contributing is too hard: the fundamental problem is that our docs are wrong more often than they are right,

Re: Builds docs on MDN

I am not sure if the reasoning applies to a community as large as Mozilla, but lately I've heard that new contributors can view a project wiki very differently from those heavily involved in a project. Copying directly from a blog post[1] on this topic: --- - Maintainers believe they're

Re: Builds docs on MDN

Also sprach Sylvestre Ledru: Le 16/06/2017 à 16:40, Boris Zbarsky a écrit : I believe we should not require filing bugs, reviews, or any of that for in-tree docs. Just edit the doc, commit, push. Add "r=documentation" if needed to placate hooks. Just because it's in-tree doesn't mean it

Re: Builds docs on MDN

Le 16/06/2017 à 16:40, Boris Zbarsky a écrit : > On 6/16/17 9:33 AM, Ehsan Akhgari wrote: >> 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 > > I believe we should not

Re: Builds docs on MDN

On 6/16/17 9:33 AM, Ehsan Akhgari wrote: 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 I believe we should not require filing bugs, reviews, or any of that for in-tree docs.

Re: Builds docs on MDN

On 6/15/17 3:41 PM, Gregory Szorc wrote: 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

Re: Builds docs on MDN

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!)

Re: Builds docs on MDN

Also sprach Andrew Halberstadt: On Fri, Jun 16, 2017 at 4:33 AM, Sylvestre Ledru wrote: As most of the people don't like to spend time writing docs, I am a bit concerned that using in-tree docs with our "heavy" review process (bug, reviewers, etc) will even decrease

Re: Builds docs on MDN

On Fri, Jun 16, 2017 at 4:33 AM, Sylvestre Ledru wrote: > As most of the people don't like to spend time writing docs, I am a bit > concerned that using in-tree docs with our "heavy" review process (bug, > reviewers, etc) will even decrease our contributions to the doc

Re: Builds docs on MDN

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

Re: Builds docs on MDN

On Thu, Jun 15, 2017 at 1:04 PM, Andrew Halberstadt < ahalberst...@mozilla.com> wrote: > +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

Re: Builds docs on MDN

+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

Builds docs on MDN

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: