There are multiple kinds of docs. One group that I've done a lot of work on is the collection of pages under https://developer.mozilla.org/en-US/docs/Mozilla/Performance. I'm not sure if in-tree would be better for those or not, but they're certainly in a different category to API docs, for example.
Nick On Wed, Jun 21, 2017 at 12:50 PM, ISHIKAWA,chiaki <ishik...@yk.rim.or.jp> wrote: > On 2017/06/21 2:19, Ehsan Akhgari wrote: > >> On 06/20/2017 12:55 PM, Benjamin Smedberg wrote: >> >>> >>> >>> On Tue, Jun 20, 2017 at 12:40 PM, Ehsan Akhgari <ehsan.akhg...@gmail.com >>> <mailto: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 >>> <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. >>> >> Something that a wiki is much more suitable for. ;-) >> >>> 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. >>> >> This is the part that I don't understand. You are implying that by not >> having some text file containing the documentation inside the tree we can't >> enforce review over documentation, and that they can't be updated alongside >> code changes. I chose the example of WebIDL bindings documentation very >> consciously to demonstrate that these are false assertions. That example >> clearly demonstrates that reviewers can (and certainly do) ask patch >> authors to fix the documentation when they make code changes, such >> documentation fixes are reviewed by the right people and the resulting docs >> stay in good shape. >> >> > I am a volunteer who occasionally submit patches to C-C TB. > > In-tree documentation is much easier for volunteers to work with. > The documentation is much closer to the code we are modifying. > > Out of tree docs are much harder to deal with. > Just adding a few (actually more) keystrokes to access them make it > rather difficult, or more to the point TIME-CONSUMING to work with. > > For unpaid volunteers (and I assume even for paid developers), in-tree > documentation is much easier to work with in terms of overhead of JUST > checking WHERE on earth the relevant documentation exists (IF IT EXISTS AT > ALL) and then out-of-tree documentation in an other system means we still > need work with DIFFERENT set of rules that exist for accountability for > modification. > > Given these overhead, out-of-tree documentations are basically something > volunteer patch submitters won't be able to work with: I suspect "Just > forget it" would be what many volunteer submitters would feel after a while. > > Initially, when people start to submit patches, they may think what they > might need to do with the documentation aside from DOCS style annotations > inside the code itself. > But then the current anarchy of documents scattered around makes you > realize finding relevant documentation is hard. You never know if you have > found all relevant documentation there is to the particular module, etc. > after google search, say. > > That's when "Forget it" makes sense :-( > > Of course, if someone points out relevant docs in an exact manner showing > URLs and such, that is another story. > But I wonder, though, whether OTHER contributors could find THOSE > DOCUMENTS on their own in the future. I bet they don't most of the times. > > The result is the almost document-less (in practical terms) > hard-to-modify C-C source tree IMHO. > > I suspect M-C is not that different in terms of document-friendliness > given some arcane bugs that were not fixed for many years. > > The reliance of web tools for documentation is a little overblown. > Relevant documents should live near the source code. > Just creating a DOC directory for each module will go a long way > - to consolidate the docs in a single place (for a module. We can > obviously have many DOC directory for each module.) > - to make the access to the docs easy, etc. > > > Success of linux is partly attributable to the in-tree documentatio. Every > single important API and design documents for modules (if any for the > latter case) lives in Documentations directory and that was great for > contributors, especially driver developers. > If major changes take place, it is obvious where to put a new document or > whether an existing document in THAT PLACE needs to be changed. > To be frank, rather than relying on a google search with many noisy hits, > I would prefer to run "grep keyword" under a single Documentations tree. Of > course, in this case, no hits means there is NO DOCUMENTATION at all. That > is life. > With mozilla's source code tree, one never knows if one's google search > failed to produce a link to an unknown important document. > > Just a perspective from an occasional patch submitter. > > TIA > > > The flip side of the coin is that collaborating on writing articles (which >> documentation writing is ultimately is all about) is just not that great of >> an experience when you approach it as rigidly as collaborating on writing >> computer code. There is a reason why people have invented wikis, >> etherpads, and software like gdocs! They provide a better model for >> collaborating on writing articles. It is true that when our only tool is a >> DVCS package, all of our problems start to look like nails. But they don't >> have to. :-) (And FWIW I'm gonna give arguing over this a rest if you >> won't agree, since this is purely subjective and I suspect at the end of >> the day we may not be able to convince each other here!) >> >>> >>> I >>> >>> The existing in-tree docs are already pretty well discoverable >>> on gecko.readthedocs.io <http://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. >>> >> FWIW previously I was just expressing sadness of the bar to contributing >> to build system docs being raised, but I'd be happy to live with it since I >> won't be doing most of the work there. But for more general discussions, >> this isn't the right venue. >> >>> >>> 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 <http://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 >>> >> Great tips, thank you! >> >>> 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! >>> >> Yeah I am also looking for ward to this feature, more for regular code >> review though. :-) >> _______________________________________________ >> 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
