Cameron, <br>
<br>
Redoing the documentation has been a task on the OL list for quite a while:<br>
<a href="http://trac.openlayers.org/ticket/419">http://trac.openlayers.org/ticket/419</a><br>
<br>
Rockstar that he is, mr. Schmidt worked his magic with the old JSDOC and managed<br>
to get some output for the current trunk. That's what we see at the index.html page. <br>
<br>
I think the idea is that we'll do a rebuild of that JSDOC html when we make the final <br>
2.4 release. You're right it's absolutely crucial to add the version number to the docs. <br>
<br>
the reference.html page is a hand-made api documentation that cr5 made many moons<br>
ago. I think we all are in agreement that it can safely be replaced by the above JSDOC<br>
documentation. It might, however, be worth going over the reference.html file because <br>
I know he spent a lot of hard work typing out the descriptions, and if we just took the time<br>
to transfer them into the jsdoc function header comments, we could preserve these helpful<br>
bits. <br>
<br>
<br>
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. <br>
<br>
<br>
My suggestion would be we make a dir structure something like this:<br>
<br>
<a href="http://www.openlayers.org/docs/index.html">www.openlayers.org/docs/index.html</a> or <a href="http://www.openlayers.org/docs.html">www.openlayers.org/docs.html</a> -- general info about documentation for the project
<br>
<br>
<a href="http://www.openlayers.org/docs/2.4/index.html">www.openlayers.org/docs/2.4/index.html</a> - generic page with links to
specific 2.4 documentation (api.html, wiki/Documentation, etc), as well
as link to the release notes page<br>
<br>
<a href="http://www.openlayers.org/docs/2.4/api.html">www.openlayers.org/docs/2.4/api.html</a> - equivalent of the current 'index.html' page. the output of the JSDOC program<br>
<br>
<br>
<br>
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. <br>
<br>
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. <br>
<br>
If anyone out there reading this has resources (time/money) they could contribute we're all ears! :-)<br>
--Erik<br>
<br><br><div><span class="gmail_quote">On 4/27/07, <b class="gmail_sendername">Cameron Shorter</b> <<a href="mailto:cameron.shorter@gmail.com">cameron.shorter@gmail.com</a>> wrote:</span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Looking around at the documentation I've found 3 locations for it.<br><br><a href="http://openlayers.org/doc/reference.html">http://openlayers.org/doc/reference.html</a><br>This seems to be run against 2.3?<br>Where is the source for this documentation? Is it in SVN? Can I find the
<br>2.4rc2 version somewhere?<br><br><a href="http://dev.openlayers.org/docs/index.html">http://dev.openlayers.org/docs/index.html</a><br>I assume this is run against 2.4rc2?<br><br><a href="http://trac.openlayers.org/wiki/Documentation">
http://trac.openlayers.org/wiki/Documentation</a><br>Is this still being maintained?<br><br>Recommendation 1:<br>* Put version number with documentation.<br><br>Recommendation 2:<br>* Deprecate at least one of the documentation locations in order to
<br>reduce developer effort required to maintain it. I suspect<br><a href="http://trac.openlayers.org/wiki/Documentation">http://trac.openlayers.org/wiki/Documentation</a> should be deprecated, or<br>at least we should remove the link to it from
<a href="http://openlayers.org">http://openlayers.org</a><br><br>--<br>Cameron Shorter<br>Systems Architect, <a href="http://lisasoft.com.au">http://lisasoft.com.au</a><br>Tel: +61 (0)2 8570 5050<br>Mob: +61 (0)419 142 254
<br><br>_______________________________________________<br>Dev mailing list<br><a href="mailto:Dev@openlayers.org">Dev@openlayers.org</a><br><a href="http://openlayers.org/mailman/listinfo/dev">http://openlayers.org/mailman/listinfo/dev
</a><br></blockquote></div><br>