Re: Builds docs on MDN

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Builds docs on MDN

Gregory Szorc-3
On Wed, Jun 21, 2017 at 9:11 PM, ISHIKAWA,chiaki <[hidden email]>
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: [hidden email] )
>
>
> TIA
>
> On Wed, Jun 21, 2017 at 3:42 PM, ISHIKAWA,chiaki <[hidden email]>
>> 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 <
>>>> [hidden email] <mailto:[hidden email]>> 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
>>> [hidden email]
>>> https://lists.mozilla.org/listinfo/dev-builds
>>>
>>>
> _______________________________________________
> dev-builds mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-builds
>
_______________________________________________
dev-apps-thunderbird mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-thunderbird
Reply | Threaded
Open this post in threaded view
|

Re: Builds docs on MDN

ISHIKAWA,chiaki
(Sorry for top-posting.)

Hi, I am not even sure if this SPHINX documentation convention is known
OUTSIDE the core mozilla paid developer community at all.

Sorry if I may sound so ignorant, but you can't really expect an
occasional bug reporter/patch contributor to install all the glitzy new
tools on the PCs and update them as the new revisions of these come out.
(Especially for documentation tools. Build toolchain needs to be updated
for apparent reasons for patch contributor even if they are occasional
contributor.)

I think we really need to have a ONE PAGE documentation guide that
specifies documentation contributor regarding
  - where to place the docs,
  - using what tools,
etc. in an easy-to-understand clear cut manner. (No exceptions, and no
long list of references.)

But obviously, there is NO consensus about the two topics and so this
ONE PAGE cannot exist today. But I bet unless such a single page doc exists,
  - we cannot expect the outside volunteer community to figure out where
the documents on particular topic are if they do exist at all,
  - we cannot expect them to "edit" them if there is no single set of
accountability rules: if there are tools or repositories such as
bugzilla/github/tools on top of github or mercurium, each with a
different set of explicit rules and implict conventions? No way.

Sorry for my negative sounding comment, but this is what an occasional
contributor feels by looking at the discussion.
I appreciate the efforts put into documentation internally at Mozilla
organization, but frankly, I don't think the organization has invested
wisely to make the documentations easily accessible.

I think FF can limp along in this manner alright by sheer volume of the
developers.

But obviously C-C TB is on the verge of being put into ICU now because
it is so tough to bring in new programmers (a few may show up each year
but given the size of code base, not enough.: it is larger than M-C,
please recall M-C is PART of TB. We have large C-C tree on top of it.)
The lack of documentation or long neglect of it, is one reason, I think.


TIA

On 2017/06/24 6:05, Gregory Szorc wrote:

> On Wed, Jun 21, 2017 at 9:11 PM, ISHIKAWA,chiaki <[hidden email]>
> 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: [hidden email] )
>>
>>
>> TIA
>>
>> On Wed, Jun 21, 2017 at 3:42 PM, ISHIKAWA,chiaki <[hidden email]>
>>> 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 <
>>>>> [hidden email] <mailto:[hidden email]>> 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
>>>> [hidden email]
>>>> https://lists.mozilla.org/listinfo/dev-builds
>>>>
>>>>
>> _______________________________________________
>> dev-builds mailing list
>> [hidden email]
>> https://lists.mozilla.org/listinfo/dev-builds
>>
> _______________________________________________
> dev-apps-thunderbird mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-apps-thunderbird
>
>

_______________________________________________
dev-apps-thunderbird mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-apps-thunderbird