Re: Reviews for in-tree documentation

2017-10-19 Thread Myk Melez
Dustin Mitchell 2017 October 19 at 10:21 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

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

2017-10-19 Thread Gregory Szorc
On Thu, Oct 19, 2017 at 6:48 PM, Daniel Veditz wrote: > On Thu, Oct 19, 2017 at 9:30 AM, smaug wrote: > > > (Hoping the r=documentation flag won't be misused ;)) > > > ​I hope there will be some kind of hook making sure files touched in that > manner are

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

2017-10-19 Thread Dustin Mitchell
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)

2017-10-19 Thread Andreas Tolfsen
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)

2017-10-19 Thread Daniel Veditz
On Thu, Oct 19, 2017 at 9:30 AM, smaug wrote: > (Hoping the r=documentation flag won't be misused ;)) ​I hope there will be some kind of hook making sure files touched in that manner are all actually documentation files and not other parts of the repo. - ​Dan Veditz​

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

2017-10-19 Thread 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 few people, this might not be an

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

2017-10-19 Thread smaug
Sounds very reasonable. (Hoping the r=documentation flag won't be misused ;)) On 10/19/2017 04:37 PM, Andreas Tolfsen wrote: Some time ago there was a discussion on dev-builds@ regarding the state of our in-tree source code documentation. The main focus was that MDN, moving forward, will

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

2017-10-19 Thread Gregory Szorc
On Thu, Oct 19, 2017 at 5:37 PM, Andreas Tolfsen wrote: > Some time ago there was a discussion on dev-builds@ regarding > the state of our in-tree source code documentation. The main > focus was that MDN, moving forward, will mainly revolve around web > platform documentation and

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

2017-10-19 Thread Andreas Tolfsen
Some time ago there was a discussion on dev-builds@ regarding the state of our in-tree source code documentation. The main focus was that MDN, moving forward, will mainly revolve around web platform documentation and would actively start de-emphasising Gecko contribution docs. Now, that