On 9/17/2012 12:03 PM, Gregory Szorc wrote:
I like the idea. However, we have a big obstacle: MDN.
Many believe that MDN should be where user-facing API documentation
lives. MDN certainly has a better user experience than foraging around
mozilla-central (especially if you are just a casual developer). If
I'm a casual extensions developer, I much prefer browsing MDN to
searching for files in the tree and looking at source code. Why are
you making me look at source code when all I need to know is how the
API works?! Good documentation alleviates the need to look at source
code. User experience matters and developers are users too. We are
right in wanting to promote a better user experience/MDN for
documentation.
My preferred source editor lets me jump to the IDL definition of an
interface with two keystrokes (Ctrl-]). Navigating to an interface on
MDN requires at least a dozen (Alt-Tab to Firefox, Ctrl-T for new tab,
MDN to get something in the tab bar, down a few times to select a short
pagename, backspace, type in the interface...). As a core developer, MDN
documentation is essentially useless to me because in-source
documentation is much easier to access. I'll agree that add-on authors
don't necessarily have this luxury.
The problem with MDN is it isn't integrated with the source tree in
any way AFAICT. So, as a developer, I have a conflict. Do I write
great docs in the tree? If so, I have to manually replicate those on
MDN. And, I have to remember to do this every time I change docs. This
takes a lot of effort, especially when you consider czars don't run
every module and changes creep in from people not as stringent about
docs as you. Alternatively, I take the lazy road and don't bother
synchronizing docs to MDN. Or, I'm ignorant about the existence of
docs on MDN and don't know they need to be updated. So, either it
takes me/developers a lot of extra work to ensure all the docs are up
to date. Or, developers who don't want to or can't afford the time to
source forage lose out because the docs don't exist or aren't up to
date. This system is set up for failure.
Source code has a great advantage in that it's much closer to the point
of definition, so reviewers can (and should, in the argument of this
thread) be pestering people who don't add the documentation. By
contrast, MDN is independently updatable, so it's not as easy to enforce
changes there. Case in point: the MDN docs for the JS Map feature still
haven't, 7 weeks and one uplift later, indicated that Map is iterable.
I'd argue things would be in a much better state if in-tree docs were
pushed to MDN or some other read-only docs site. I'm arguing for the
docs to live in the tree because from my experience the closer the
docs are to the things they describe (typically source code), the
higher the likelihood that they are up to date because of their higher
visibility to developers. At some point you'll want to consider
higher-level docs in a medium that is easier to edit than our source
tree. I'm not sure where to draw that line. Certainly things like IDL
and class documentation should be pulled from source and read-only.
But, that line get blurry pretty fast.
There's good news and bad news here. The good news is that we have |make
documentation|, and, for a time, this was being automatically updated on
doxygen.db48x.net. If you've ever seen weird graphs of things in MXR,
they're files being mapped from said site. |make documentation| is a
command which runs Doxygen over the files in dist/include and dist/idl
(we have a config file checked into the tree already). The bad news is
that Doxygen these days seems to be stuck processing our code, and that
it has a nasty habit of tripping over some of our macro usages a lot.
This also does nothing to solve the issue of documentation for JS
modules or any front-end content (like various XBL definitions or JS
window global objects).
The other issue is that we also have effectively 5 distinct versions of
code (mozilla-esr, release, beta, aurora, central) building 4-6 projects
(Firefox, XUL runner, Firefox for Android, Firefox OS, and Thunderbird
and SeaMonkey, if you include the comm-* portion of the tree) on several
platforms. If you look at just the C/C++/IDL portion of the effective
public interface, platform differences probably don't matter that much
(add things not exported and there's a bigger difference), but the
front-end segment of the effective interface is wildly different on
various platforms.
_______________________________________________
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform
