On Wed, Jun 21, 2017 at 9:11 PM, ISHIKAWA,chiaki <ishik...@yk.rim.or.jp> wrote:
> > (I am posting a response to Ehsan's message which somehow was garbled and > he kindly corrected in a personal exchange.) > > > On 2017/06/22 6:10, Ehsan Akhgari wrote: > >> Oops, not sure how that happened, sorry about that! But that formatting >> corruption seemed to have happened in the text I quoted. Here is the >> newly >> added text in my email: >> >> Right, and even depending on the kind of API docs, if you want to exceed >> beyond a paragraph or two, keeping the API docs next to the code quickly >> loses all of its theoretical benefits. For example, think about how we'd >> fit something like <https://developer.mozilla.org >> /en-US/docs/Web/API/Background_Tasks_API> next to < >> https://searchfox.org/mozilla-central/rev/714606a8145636d93 >> b116943d3a65a6a49d2acf8/dom/webidl/Window.webidl#495>. >> > > Well, I am not advocating the direct inclusion of complex documents in > .idl file or C++/Java/etc. source files. > (Is this implied in the above paragraph. Sorry my native language is NOT > English and so sometimes, I lose the nuances.) > > On the other hand, if we can keep the original document files in a well > known fixed directory, say, "Documentation" directory, e.g, in this case, > m-c/dom/webidl/Documentation or > m-c/dom/Documentation, it will be much easier for occasional contributors > to figure out where the related documentation to the source code they are > modifying exists IF ANY. > BTW I wonder if each file pointed by an entry in > https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API > has been generated by javadoc or other documentation tools form the > annotation in source files themselves(?) They look so, but I am not sure. > We already kinda have this convention. The SPHINX_TREES moz.build variable allows you to define directories containing docs ( https://gecko.readthedocs.io/en/latest/#adding-documentation) and the convention seems to be a "docs" directory ( https://dxr.mozilla.org/mozilla-central/search?q=SPHINX_TREES&case=true). (This ability to aggregate files from multiple directories was something I added to the in-tree Sphinx docs because I anticipated people wanting the docs to live closer to the components they are documenting.) Unfortunately, I don't think a unified docs directory for all of mozilla-central is tenable. We've historically thought of mozilla-central as one large project. In reality, there are multiple projects inside. I think we need to get better about formalizing boundaries between components (including their documentation) because that will make it easier to leverage sparse checkouts, builds/scheduling of specific components, etc. What we can do is improve the tooling for findings docs. I think something like `mach doc --list` or even showing the sources of the docs in the generated docs would go a long way. > > In the case of Linux, there is a Documentation directory near the top of > the source tree and the directory hierarchy under this "Documenation" > reflects the module hierarchy of the real source tree. > Thus you can find SCSI subsystem documents (especially related to driver > files) below > Documentation/scsi > > Documentations applicable the kernel as a whole often resides directly > below Documentation directory. > > My point is that a simple command below will find ALL the "official" linux > documentation about a keyword. If there is no hit, then there is NONE. > > find /usr/src/linux-source-4.9/Documentations -type f -print | xargs > egrep -i searched_keyword > > The documentation files are plain text. > (There ARE a few exceptions. I found Documentation/sound/alsa/seq_oss.html > with the following command. > find Documentation/ -name "*.html" -print > > I also found a DocBook stylesheet under this directory with > find Documentation/ -name "*.x*" -print > Documentation/DocBook/stylesheet.xsl > > >> But the discoverability issue you brought up is a real issue, and is a >> very >> easy one to solve for out of tree docs incidentally with a simple >> moz.build >> annotation similar to BUG_COMPONENT, I think. >> >> > I am not sure here. > Are you advocating a keyword value pair in the document to make it easy to > search by Google? > > I want to make it easy to access the documentation even without such trick > by creating a single place where such documents reside. > (Yes, this directory could be large. But so is the rest of the source > tree. In this sense, the documentation directory does not have to be within > M-C/C-C, etc. It could be D-C directory with its own repository. > Making it easy to find by having a SINGLE repository is an idea. > > In linux's case, that is "Documentation" directory. > For official documents, that is it. It happens to be inside the source > tree as well under same git management (I think.) > > In the case of linux, there can be other tutorials written for mortals, > but we can always check the Documentation directory for any final word from > module maintainers, driver writers and such. > I think this has helped the contribution from volunteers. > > I wonder if we can consolidate all the documentation pieces in one > directory/repository (or be part of the source tree if it is tenable). > > Again this is a perspective from an occasional patch contributor who > always cringe at the lack of overall design documents of C-C TB internal > (this can live in for example C-C/mailnews/Documentation/ top-level IMHO). > > My position is that all the bugzilla entries will pale with such documents > MOST the times in terms of accessibility. I have no idea how many times I > search bugzilla for certain information. It would have been vastly superior > that such knowledge is condensed over the years by someone who need it into > documentation files under Documentation directory and kept up-to-date. > [And it has been done in the case of Linux.] > > Plain text works, BTW. > > If we need contributors, we should make it easy for contributors to learn > the code. I suspect I should propose this documentation approach to C-C TB > maintainers who need every help they can find to court volunteers. > (Adding cc: dev-apps-thunderb...@lists.mizilla.org ) > > > TIA > > On Wed, Jun 21, 2017 at 3:42 PM, ISHIKAWA,chiaki <ishik...@yk.rim.or.jp> >> wrote: >> >> Dear Ehsan, >>> >>> Something went wrong with the formating of your e-mail post. >>> >>> Would you like to re-post this if your local copy retains the sane >>> formating somehow? >>> >>> Chiaki Ishikawa >>> >>> >>> On 2017/06/21 23:49, Ehsan Akhgari wrote: >>> >>> On 06/21/2017 12:04 AM, Nicholas Nethercote wrote: >>>> >>>> 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. >>>> Right, and even depending on the kind of API docs, if you want to exceed >>>> beyond a paragraph or two, keeping the API docs next to the code quickly >>>> loses all of its theoretical benefits. For example, think about how >>>> we'd >>>> fit something like <https://developer.mozilla.org >>>> /en-US/docs/Web/API/Background_Tasks_API> next to < >>>> https://searchfox.org/mozilla-central/rev/714606a8145636d93 >>>> b116943d3a65a6a49d2acf8/dom/webidl/Window.webidl#495>. >>>> >>>> But the discoverability issue you brought up is a real issue, and is a >>>> very easy one to solve for out of tree docs incidentally with a simple >>>> moz.build annotation similar to BUG_COMPONENT, I think. >>>> >>>> > [I removed the incorrectly formatted my earlier comment and replaced it > with a correctly formatted one. Thunderbird bug? Hmm... > Hope this shows up correctly. I am using TB myself.] > > 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
