On 06/22/2017 12:11 AM, ISHIKAWA,chiaki 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.)
Oh, I see. I guess I read too much into "close to code" in your email!
Sorry about that. :-)
Now that I read it again, it doesn't really advocate that at all.
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.
(No pretty sure they aren't.)
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
I think the Linux model of in-tree documentation still has the usability
issue of not being very user-friendly for writing documentation (I
personally find the current MDN wiki a very nice documentation editing
UI, but this is subjective, and I understand if some people prefer plain
text files here), but I agree that it does provide some general benefits
around making the documentation more easily searchable and navigatable
locally.
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?
No, something to make it easier for people to find the relevant
documentation on the web by documenting the URL to the documentation in
a consistent way.
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).
FWIW the Linux model has some nice aspects to it, but our in-tree
documentation model is more geared towards Sphinx documentation
generation, so it's fairly different. I don't really know how to
balance out my desire for a wiki like editing interface with yours of
having all of the documentation in one place, but at any rate we
currently are discussing three alternatives it seems. I think
unsurprisingly different people prefer different solutions here...
Cheers,
Ehsan
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
