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/714606a8145636d93b116943d3a65a6a49d2acf8/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.
On Wed, Jun 21, 2017 at 12:50 PM, ISHIKAWA,chiaki > <ishik...@yk.rim.or.jp <mailto: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> >
<mailto: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> >
<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>
<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> > <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 >
<mailto:dev-builds@lists.mozilla.org> >
https://lists.mozilla.org/listinfo/dev-builds >
<https://lists.mozilla.org/listinfo/dev-builds> > > > >
_______________________________________________ dev-builds mailing >
list dev-builds@lists.mozilla.org >
<mailto:dev-builds@lists.mozilla.org> >
https://lists.mozilla.org/listinfo/dev-builds >
<https://lists.mozilla.org/listinfo/dev-builds> > >
_______________________________________________
dev-builds mailing list
dev-builds@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-builds
