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, 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. 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: 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. 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? --BDS On Fri, Jun 16, 2017 at 10:37 PM, Ehsan Akhgari <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 >> >> - Ryan >> >> On Fri, Jun 16, 2017 at 10:05 AM, Sylvestre Ledru <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> >> 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 >> > > _______________________________________________ > dev-builds mailing list > dev-builds@lists.mozilla.org > https://lists.mozilla.org/listinfo/dev-builds >
_______________________________________________ dev-builds mailing list dev-builds@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-builds
