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 the record it's
not clear to me how you connect that to it being a better choice for the
said documentation to live in the tree. (Since you mentioned the
anecdotal successful example of telemetry ping documentation, let me
counter it with the anecdotal successful example of WebIDL bindings
documentation which lives out of the tree:
https://developer.mozilla.org/en-US/docs/Mozilla/WebIDL_bindings.)
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, and there is very poor ability
to get rid of old docs or even see all the docs that currently exist.
We cannot afford to have documentation be somebody else's problem,
where "volunteers will get to it".
I don't think we can have a sustainable codebase and community (paid
and volunteer) without some fundamental improvements in the way we
handle code documentation. Documentation needs to be part of everyday
engineering and needs to happen in step with changes in our internal
APIs and code structure, rather than as something that happens
after-the-fact. Technical writing is a skill that we should be
actively teaching senior engineers in the project.
This is a matter that is totally irrelevant to where the documentation
lives, FWIW. :-)
I'd even go farther and say that we should keep some kind of review
requirements on documentation, although with perhaps different rules:
e.g. module owners and peers can change docs without external review.
The existing in-tree docs are already pretty well discoverable on
gecko.readthedocs.io <http://gecko.readthedocs.io>: as an example,
searching for "mozilla main ping" has the readthedocs documentation of
the main ping at the top spot.
I agree that as we grow scope and breadth of in-tree docs we're going
to need better organization and probably different templates. I don't
know if that's something mhoye would be willing to own as community
manager? Or if not let's raise that as a need to engineering
directors. There are a bunch of options, including things like
integrating more directly with DXR, the way markdown checked into
github repositories renders automatically in the github repo browser.
So this thread is about *build system* docs. Now it seems we are
talking about all docs?
I've found it almost automatic to modify existing docs. Adding *new*
docs is a bit of a pain, because the build machinery isn't obvious.
Perhaps we could write down exactly where the overhead lies and
actually make this better?
For the record, I think the in-tree documentation system could use some
documentation on how it should be used (in case there isn't some already
available for it.) For example I am not sure what's the process for an
update to something in the tree to go to the live site, how would the
different versions of the docs living on the different branches
(central/beta etc) get treated differently (for example how should one
document something that changed on central before the change hits the
rest of the channels?), how to preview the edits I'm making, how to
subscribe to notifications (similar to watching a wiki page), etc.
Cheers,
Ehsan
On Fri, Jun 16, 2017 at 10:37 PM, Ehsan Akhgari
<ehsan.akhg...@gmail.com <mailto:ehsan.akhg...@gmail.com>> wrote:
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 pull request currently.
As someone with commit access, even if we lifted all requirements
to file bugs, get reviews etc from the process, I'd still find the
overhead of contributing to in-tree documentation too high
personally unless if my contribution was something I would really
consider "worth it". I think moving docs into the tree will
exclude the kind of casual contributor who doesn't even know how
to bypass all of our process to get their contribution
"accepted". Compare this to the current world where they don't
need to ask for anyone's blessing beforehand in the first place. :-/
[1]:
http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation
<http://www.yesodweb.com/blog/2015/08/thoughts-on-documentation>
- Ryan
On Fri, Jun 16, 2017 at 10:05 AM, Sylvestre Ledru
<sylves...@mozilla.com <mailto:sylves...@mozilla.com>
<mailto:sylves...@mozilla.com <mailto:sylves...@mozilla.com>>>
wrote:
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 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. :(
And far from trivial for volunteers who just want to fix
one or two
things in the doc :/
S
_______________________________________________
dev-builds mailing list
dev-builds@lists.mozilla.org
<mailto:dev-builds@lists.mozilla.org>
<mailto:dev-builds@lists.mozilla.org
<mailto:dev-builds@lists.mozilla.org>>
https://lists.mozilla.org/listinfo/dev-builds
<https://lists.mozilla.org/listinfo/dev-builds>
<https://lists.mozilla.org/listinfo/dev-builds
<https://lists.mozilla.org/listinfo/dev-builds>>
_______________________________________________
dev-builds mailing list
dev-builds@lists.mozilla.org <mailto:dev-builds@lists.mozilla.org>
https://lists.mozilla.org/listinfo/dev-builds
<https://lists.mozilla.org/listinfo/dev-builds>
_______________________________________________
dev-builds mailing list
dev-builds@lists.mozilla.org <mailto:dev-builds@lists.mozilla.org>
https://lists.mozilla.org/listinfo/dev-builds
<https://lists.mozilla.org/listinfo/dev-builds>
_______________________________________________
dev-builds mailing list
dev-builds@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-builds
