[dojo-contributors] Thoughts on API documentation

James Burke jburke at dojotoolkit.org
Fri May 30 20:35:21 EDT 2008


These are some questions/issues I have had with the way we do API
documentation. I was not sure how to raise them before because I did
not feel like I saw the end goal clearly. Also, many of you, and in
particular Neil, are much more talented engineers than I am, and I
felt like I might be asking silly questions. But I cannot seem to
resolve these questions/issues for myself, so I am laying them out
now.

Online vs. Offline
====================
I feel like the process of generating and using API documentation
should be easier. The use case for using a PHP/DB system seems to be
to enable comments. Generating a set of "offline" or static API
documents seems to be a second-tier goal.

I would rather see the primary goal to be generating offline/static
API documents that could be delivered as part of the distributions,
then use a JSONP-type API to the Dojo server to pull in comments. That
way, I could at least view the API while offline or in a faster
fashion than depending on the availability and responsiveness of
dojotoolkit.org (which has been an issue, and will be in the future).

Going the "use the server just for comments" also feels like less of a
resource impact on our DB and our website: just limiting it to
managing comments. It also means if the server cannot respond, I can
still view docs.

Also, having a way to generate docs without installing and configuring
PHP would be nice.

Custom vs. off the shelf
==================
I am not sure we should be developing a custom documentation system
anyway. We clearly do not have time for it. It took a very long time
to get it up and running (no one's fault, we're all busy -- I
certainly could have done more doc comments), and it still feels less
than 100%. Going with an "off the shelf" documentation solution from
the start seems like it would have saved time: we could have started
sooner and gotten quicker feedback on the doc output.

Maybe things like dojo.provide/dojo.require makes using an existing
doc system hard to do, I do not know. Feel free to enlighten me. But
maybe the way to solve it is enhancing an existing tool vs making our
own.

Doc format
===================
I am not sure developing our own syntax for the comments has worked
out. I appreciate the dynamic nature of JavaScript, but it seems like
we have to go through some hoops to get our syntax to work out anyway.
It seems like we could just take the hit of jumping through hoops to
use another syntax. I do not feel it was a net gain.

I am also not a fan of having to learn markdown. It bothers me that I
have to use a white space-aware syntax, and a syntax I do not use on a
regular basis. I would prefer to use HTML. HTML is something all
users/contributors already know if they are doing web development. But
I appreciate this could be a bikeshed, personal taste issue.

Conclusion
==================
I appreciate that we were trying to do something that imposed less of
a tax on contributors to document the code, and to document JavaScript
better. However, any sort of tax reduction on the contributor front
seems marginal, particularly compared to the tax we have imposed on
our users:
- having to wait so long for documentation
- having to depend on the availability of dojotoolkit.org
- not making it clear what version api.dojotoolkit.org is pointing to
or how to get specific versions
- a fairly high cost of entry to use the doc system to generate docs
(installing/configuring PHP, dealing with the output).
- no offline docs by default.

And for me at least, having to learn a "non-standard" doc format and
having to use markdown were additional taxes on me -- learning our doc
system did not result in a skill I can apply to other codebases, since
it is custom.

What we have is certainly useful, but it does not seem like we
documented our APIs better than other toolkits.

Possible Options
=================
So, again, this is just my opinion. I am fairly ignorant on
documentation systems, so I could just be seeing personal problems and
missing the big issues our system solves. Please clue me in.

My biggest issue is the lack of offline/static docs that are portable
and easy to generate. The off-the-shelf solution and custom doc syntax
issues are lesser concerns, and perhaps the problem domain requires
them.

If at least some of these issues seem valid, here are some possible
ways to address it. These are ordered from perhaps easiest to hardest,
or at least these things could be done in stages.

- Output static HTML by default. Maybe use the XML intermediate format
from the doc system now and do some
transform on that?

- Deliver the static HTML on download.dojotoolkit.org.

- Convert api.dojotoolkit.org to use static HTML, and create a
versions page. Do not generate/serve docs for trunk on
api.dojotoolkit.org: trunk users can look at code (or maybe use rhino
task mentioned below?).

- Create a JS library and JSONP API that loads comments from the
server. This library should fail gracefully if the host is not
available.

- Convert doc building to use Rhino so a "docs" command can be run
from util/buildscripts or util/docscripts. Or something that does not
require extra tools other than what we can check into the tree or
something easy to download. Making sure PHP is installed and
configured, to me, is an onerous requirement.

- Convert code to use off-the-shelf documentation system? I do not
really care, just something that seems to be in general use that
supports HTML formatting. I appreciate this might be a harder,
bikeshed task to consider, and maybe they do not work for things like
dojo.require/provide. But if not, is enhancing an existing tool an
option instead of building out our own?

Sorry for the long email. I do not want to take away from the progress
we have already made, or retread old discussions that I do not recall.
I just have had a hard time resolving these things for myself, and I
am hoping to get help with it.

James



More information about the dojo-contributors mailing list