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

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Andreas Tolfsen-2
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 discussion paints the backdrop for this new thread, but it
is well worth reading on its own and had a lot of good ideas in it
that never materialised:

        https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/Xqy_nHV5DAAJ

The reality four months on is that more documentation than ever
lives in the tree, and there is a sentiment that imposing the
same rigorous peer review process we have for source code on
documentation changes is overkill.

bz made a modest proposal that documentation changes should not
require bugs or reviews, and that they could be annotated with a
special review 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 <[hidden email]>
Date: June 16, 2017 15:40
Subject: Re: Builds docs on MDN
To: [hidden email]

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.  Just edit the doc, commit, push.  Add
"r=documentation" if needed to placate hooks.  Just because it's
in-tree doesn't mean it needs to use the whole heavyweight process.
And if we can make these things auto-DONTBUILD, that's even better,
of course.

I agree it's still slower than a wiki. :(
_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds
Reply | Threaded
Open this post in threaded view
|

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

Gregory Szorc-3
On Thu, Oct 19, 2017 at 5:37 PM, Andreas Tolfsen <[hidden email]> 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 would actively start de-emphasising Gecko
contribution docs.

Now, that discussion paints the backdrop for this new thread, but it
is well worth reading on its own and had a lot of good ideas in it
that never materialised:

        https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/Xqy_nHV5DAAJ

The reality four months on is that more documentation than ever
lives in the tree, and there is a sentiment that imposing the
same rigorous peer review process we have for source code on
documentation changes is overkill.

bz made a modest proposal that documentation changes should not
require bugs or reviews, and that they could be annotated with a
special review 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.

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 <[hidden email]>
Date: June 16, 2017 15:40
Subject: Re: Builds docs on MDN
To: [hidden email]

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.  Just edit the doc, commit, push.  Add
"r=documentation" if needed to placate hooks.  Just because it's
in-tree doesn't mean it needs to use the whole heavyweight process.
And if we can make these things auto-DONTBUILD, that's even better,
of course.

I agree it's still slower than a wiki. :(
_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds


_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds
Reply | Threaded
Open this post in threaded view
|

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

Sylvestre Ledru
In reply to this post by Andreas Tolfsen-2
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 issue. 

Sylvestre 
Le jeu. 19 oct. 2017 à 17:38, Andreas Tolfsen <[hidden email]> a écrit :
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 discussion paints the backdrop for this new thread, but it
is well worth reading on its own and had a lot of good ideas in it
that never materialised:

        https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/Xqy_nHV5DAAJ

The reality four months on is that more documentation than ever
lives in the tree, and there is a sentiment that imposing the
same rigorous peer review process we have for source code on
documentation changes is overkill.

bz made a modest proposal that documentation changes should not
require bugs or reviews, and that they could be annotated with a
special review 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 <[hidden email]>
Date: June 16, 2017 15:40
Subject: Re: Builds docs on MDN
To: [hidden email]

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.  Just edit the doc, commit, push.  Add
"r=documentation" if needed to placate hooks.  Just because it's
in-tree doesn't mean it needs to use the whole heavyweight process.
And if we can make these things auto-DONTBUILD, that's even better,
of course.

I agree it's still slower than a wiki. :(
_______________________________________________
dev-platform mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-platform

_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds
Reply | Threaded
Open this post in threaded view
|

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

Andreas Tolfsen-2
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 few people, this might not be an issue.

I don’t have these numbers, but gps had some thoughts on how
to potentially allow on-line GitHub editing PRs to m-c for
below-commit-level-3 changes that you can read more about in the
other thread [1].  Perhaps that is a way to make drive-by community
contributions to in-tree documentation easier.

My primary concern is to first fix the papercut of having to channel
changes to existing in-tree documentation through the same review
process as regular source code.

  [1] https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/MQUHhqX-DAAJ
_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds
Reply | Threaded
Open this post in threaded view
|

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

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 documentation is developer-focused, meaning anyone
understanding its content deeply should generally be an experienced
developer.

At the most, I can see using a documentation edit as an exercise in
going through the patch / review / land process for a contributor who
I would then urge on to more substantive tasks (which may also involve
substantive doc updates).

All of which is to say, yes, I'd like to see the numbers on this and I
think we should use those numbers to think carefully about whether the
proposal merits the cost in complexity, implementation time, and
security risk.

Dustin

2017-10-19 13:13 GMT-04:00 Andreas Tolfsen <[hidden email]>:

> 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 few people, this might not be an issue.
>
>
> I don’t have these numbers, but gps had some thoughts on how
> to potentially allow on-line GitHub editing PRs to m-c for
> below-commit-level-3 changes that you can read more about in the
> other thread [1].  Perhaps that is a way to make drive-by community
> contributions to in-tree documentation easier.
>
> My primary concern is to first fix the papercut of having to channel
> changes to existing in-tree documentation through the same review
> process as regular source code.
>
>  [1]
> https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/MQUHhqX-DAAJ
>
> _______________________________________________
> dev-builds mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-builds
_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds
Reply | Threaded
Open this post in threaded view
|

Re: Reviews for in-tree documentation

Myk Melez-4
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 being documented, not by someone new to the
project. And this documentation is developer-focused, meaning anyone
understanding its content deeply should generally be an experienced
developer.
Documentation may best be written by such developers, but it can be revised by anyone. And new developers seem even more likely to notice the inaccuracies in our docs that prevent them from successfully building Firefox and using its APIs.

At the most, I can see using a documentation edit as an exercise in
going through the patch / review / land process for a contributor who
I would then urge on to more substantive tasks (which may also involve
substantive doc updates).
I agree that it isn't worth optimizing the documentation process for documentation-only contributors. But it's worth optimizing for revisions by developers who don't have commit access.

-myk


_______________________________________________
dev-builds mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-builds