[OpenLayers-Dev] NaturalDocs

[Erik Uzureau]

Dear Dev,

As we've all known for a long time now, the OpenLayers project has
been in dire need of some serious documentation. We have tried hand
creating it in text files, in wikis, using jsdoc, even writing our own
version of jsdoc (cr5!).

And then, as if by divine intervention, a post came in to the dev list
last week from Glen S. about a tool called "Natural Docs".

Our esteemed contributor Tim S. took to it immediately, creating his
own sandbox[1] where he began playing around with the tool and adding
the new NaturalDocs (ND) style comments.

Chris Schmidt and I have looked over the great work that Tim has done
and we are both convinced that ND is the best solution we've seen yet
for getting a clean set of dynamically created docs up and running for
the OpenLayers project. Other members of the steering committee have
also been vocal about their approval.

The move to running automatic ND doc creation and
therefore shifting our coding style accordingly will likely go to
an official vote in the PSC sometime later this week.

Before we do so, we want to run this by the
community one more time. Please, if you have a spare moment, take a
look at the wiki[2] that Tim has created which very clearly explains
the changes we'll need to make to run ND on the project. Check out the
live ND docs[3] which are being generated from Tim's sandbox.

If there's something you don't like, or maybe something you think we
haven't thought of, please send a post to this list -- we want your
input!

If you like what you see and want to help us out with the conversion,
send me an email and you can join us with the translation of the
different sections.

If all goes well, we could have this great new system up and running
by the end of this week or early next. Again, big thanks going out to
Glen for recommending this tool and especially to Tim S who has
benevolently and almost single-handedly taken it from an idea into a
reality.

Let us know what you think!

--Erik


[1] http://dev.openlayers.org/sandbox/tschaub/naturaldocs/
[2] http://trac.openlayers.org/wiki/NaturalDocs
[3] http://dev.openlayers.org/naturaldocs