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 documentatio

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)

I would like to know what steps > to take next to make that policy. > > -- >8 -- > From: Boris Zbarsky > Date: June 16, 2017 15:40 > Subject: Re: Builds docs on MDN > To: dev-builds@lists.mozilla.org > > On 6/16/17 9:33 AM, Ehsan Akhgari wrote: > > I certainly feel li

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

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 > Date: June 16, 2017 15:40

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

flag to pass pre-receive hooks. I’m including his original email below. If we still feel this is a good idea I would like to know what steps to take next to make that policy. -- >8 -- From: Boris Zbarsky Date: June 16, 2017 15:40 Subject: Re: Builds docs on MDN To: dev-builds@lists.mozilla.org

Re: Builds docs on MDN

On Wed, Jun 21, 2017 at 9:11 PM, 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 fo

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. H

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 >> > > I believe we shou

Re: Builds docs on MDN

On 06/21/2017 12:04 AM, Nicholas Nethercote wrote: 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: 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 example

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 mailto:ehsan.akhg...@gmail.com>> wrote: On 06/20/2017 11:21 AM, Benjamin Smedberg wrote: Coming in late to this thread, but I'd like to stro

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 mailto:ehsan.akhg...@gmail.com>> 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 in

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 post is mostly advocating t

Re: Builds docs on MDN

I think it's also worth mentioning that if we get github pull request support (which afaik is still being planned?), then we could set up our doc generation such that each page links back directly to github's edit mode (at the bottom in small font), e.g: https://github.com/mozilla/gecko-dev/edit/ma

Re: Builds docs on MDN

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 post is mostly advocating that we should write documentation, which is hard to argue with. For

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, an

Re: Builds docs on MDN

On 06/16/2017 11:22 AM, J. Ryan Stinnett wrote: The post goes on to suggest in-tree documentation kept up to date via pull requests as the better approach. I guess the trouble is that at least for mozilla-central, there isn't really a low barrier approach to submitting an in-tree change like a

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 s

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 nee

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 requi

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 MD

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

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 our contributions to the d

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 (instead of > the MDN wiki

Re: Builds docs on MDN

Le 15/06/2017 à 22:22, Gregory Szorc a écrit : > On Thu, Jun 15, 2017 at 1:04 PM, Andrew Halberstadt > mailto: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 differen

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: https://developer.mozilla.org/en-US/search?q=firefox%20build