On 9/17/12 10:40 AM, Justin Lebar wrote:
Many believe that MDN should be where user-facing API documentation lives.
Who's the user here? Add-on developers, Gecko developers, or
something else? It sounds like maybe you mean Gecko developers?
I really don't think the task of Gecko developers, casual or
otherwise, would be made substantially easier if documentation about
more of our classes was available on MDN, in the form an automated
from-source translation.
Easy search of and navigation around our source is key to effective
Gecko development. But once that, you can quickly access the relevant
in-source docs. So inasmuch as you think it's hard for casual
developers to use our in-source documentation, I think it would be
helpful to focus on the question of how to improve upon tools like MXR
and DXR.
(Personally, I use grep plus a simple vim plugin [1] which lets me go
straight to a grep result within vim for 98% of my searches. I don't
know how anyone manages to use anything less-streamlined on a regular
basis. :)
Both you and Joshua shared similar viewpoints about how you don't think
we have a problem because search and navigation of source solves it.
That may be accurate - but it applies mostly to [seasoned] Gecko developers.
I'm more concerned about casual developers: people who don't code in
Gecko like it's their job. The number of these casual developers (most
add-on developers are in their ranks) vastly outnumber the number of
core Gekco developers (although not on this list).
Casual developers have a problem that seasoned Gecko developers don't
have: discovery. They need to discover what features/APIs are available
so they can implement a specific task. Gecko developers don't have this
problem because, well, they already know about everything or at least
know where to look.
grep is not a suitable discovery mechanism for casual developers. What
they want is a categorized list. Something like [1]. And, this should be
easily accessible. |make documentation| doesn't count because it
requires obtaining a source tree. We should be lowering the barrier to
entry, not increasing it. i.e. we shouldn't require people to download
or build the source to develop extensions.
I initially stated that I thought MDN would be a good place for
from-source docs. This is only because I think MDN is the logical place
for it because it's the natural developer hub. If these docs existed on
MXR or DXR instead, that's a step in the right direction. But, we'd
still have a problem with MDN fragmenting the docs. As long as there is
manual duplication between in-source docs and other systems like MDN,
casual developers lose.
[1] https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference_group
_______________________________________________
dev-platform mailing list
[email protected]
https://lists.mozilla.org/listinfo/dev-platform
