[OpenLayers-Dev] Documentation sources and versions

[Erik Uzureau]

Cameron,

Redoing the documentation has been a task on the OL list for quite a while:
http://trac.openlayers.org/ticket/419

Rockstar that he is, mr. Schmidt worked his magic with the old JSDOC and
managed
to get some output for the current trunk. That's what we see at the
index.html page.

I think the idea is that we'll do a rebuild of that JSDOC html when we make
the final
2.4 release. You're right it's absolutely crucial to add the version number
to the docs.

the reference.html page is a hand-made api documentation that cr5 made many
moons
ago. I think we all are in agreement that it can safely be replaced by the
above JSDOC
documentation. It might, however, be worth going over the
reference.htmlfile because
I know he spent a lot of hard work typing out the descriptions, and if we
just took the time
to transfer them into the jsdoc function header comments, we could preserve
these helpful
bits.


The wiki/Documentation part is maybe a little outdated, but I think it's an
important set of pages to keep up there, since it is wiki and therefore as
people discover things and/or feel generous about helping other people out,
they can contribute. I think we should maintain this, but (as you suggest)
somehow incorporate versioning information into these files. I don't think
we want to have whole separate wiki pages for each class for each version...
maybe the best way would be to just have one set of wikis for each class,
and have folks add a note to each addition specifying which version the
change applies to.


My suggestion would be we make a dir structure something like this:

www.openlayers.org/docs/index.html  or www.openlayers.org/docs.html --
general info about documentation for the project

www.openlayers.org/docs/2.4/index.html - generic page with links to specific
2.4 documentation (api.html, wiki/Documentation, etc), as well as link to
the release notes page

www.openlayers.org/docs/2.4/api.html - equivalent of the current 'index.html'
page. the output of the JSDOC program



That's my off the cuff thoughts. Of course, the real question here is *who*
is going to have time to tackle any of this. The reason that ticket has sat
unnoticed and been pushed from release to release is that people generally
find it more exciting to work on feature development than project
maintenance... and practically no one likes to work on documentation.

I personally would *love* to tackle this task, but my employment situation
at the moment does not allow  me the time that would be necessary to do this
all and do it well.

If anyone out there reading this has resources (time/money) they could
contribute we're all ears! :-)
--Erik


On 4/27/07, Cameron Shorter <cameron.shorter at gmail.com> wrote:
>
> Looking around at the documentation I've found 3 locations for it.
>
> http://openlayers.org/doc/reference.html
> This seems to be run against 2.3?
> Where is the source for this documentation? Is it in SVN? Can I find the
> 2.4rc2 version somewhere?
>
> http://dev.openlayers.org/docs/index.html
> I assume this is run against 2.4rc2?
>
> http://trac.openlayers.org/wiki/Documentation
> Is this still being maintained?
>
> Recommendation 1:
> * Put version number with documentation.
>
> Recommendation 2:
> * Deprecate at least one of the documentation locations in order to
> reduce developer effort required to maintain it. I suspect
> http://trac.openlayers.org/wiki/Documentation should be deprecated, or
> at least we should remove the link to it from http://openlayers.org
>
> --
> Cameron Shorter
> Systems Architect, http://lisasoft.com.au
> Tel: +61 (0)2 8570 5050
> Mob: +61 (0)419 142 254
>
> _______________________________________________
> Dev mailing list
> Dev at openlayers.org
> http://openlayers.org/mailman/listinfo/dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/openlayers-dev/attachments/20070427/24ec0cdf/attachment.html