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
