On Tue, Jun 20, 2017 at 12:40 PM, Ehsan Akhgari <ehsan.akhg...@gmail.com> wrote:
> 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.) > I'll put nuance on this. I do think we should be writing docs, but I think it's much more important that we're maintaining and deleting existing docs as the code changes or becomes irrelevant. That's why I think the choice of in-tree versus external tool is important and not merely a tooling choice. Documentation that is in the tree can/should be reviewed as the code changes. Partly because it is in the tree, it maps to Mozilla module ownership and module owners can exercise ownership over their slice of documentation explicitly. > I > >> 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? > gps proposed a specific change for build system docs, but the pushback he's getting isn't about build docs in particular but about docs in general. Therefore I think it's important to address this generally. > 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. > I agree this is good, and I'll file a bug about this specifically, but I'll answer the questions here: As docs land to mozilla-central they will automatically update gecko.readthedocs.io. There is a taskcluster job which reports to the mozilla-central tree which does this automatically, and it turns red on failure for monitoring. As far as I know, docs from the other trees do not get automatically published anywhere, and we don't currently host archived release versions of the docs. To preview local edits, run `./mach doc` which will do local generation Currently we don't have good notifications for changes to any file in-tree (at least that I know of). This is one of the phabricator features that I am most looking forward to! --BDS
_______________________________________________ dev-builds mailing list dev-builds@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-builds
