info
Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
Re: Reviews for in-tree documentation
20 views
Skip to first unread message
Myk Melez
Oct 19, 2017, 2:06:21 PM10/19/17
to Dustin Mitchell, dev-builds, Sylvestre Ledru, Boris Zbarsky, dev-platform
> Dustin Mitchell <mailto:dus...@mozilla.com>
> 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
> 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
0 new messages