[OpenLayers-Dev] OL Documentation Improvement

[Peter Robins]

On 4 May 2012 07:13, Keith Moss <Keith.Moss at landgate.wa.gov.au> wrote:
> We've been developing with OpenLayers a lot this past year and from time to
> time and there have often been times when we could have provided a helpful
> addendum to one or another piece of documentation. Has the option of
> allowing user comments on the documentation been considered? They're quite
> useful in the case of the PHP manual, for example.

can you give some examples of where you would want to add comments
rather than improve the actual docs? As Chris says, it's easy to edit
both api docs and docs.openlayers.org with git/hub and issue a pull
request, which has the added advantage that experienced developers can
check what's proposed is actually correct :-) And you can easily raise
an issue if you want to discuss something.

I don't think the PHP manual is really comparable. I have found the
comments there useful for giving examples of how to do things, but OL
already provides a large number of examples (something PHP doesn't
have), and ISTM if you want to add something. the best way to do this
is to submit an additional example, or possibly change one of the
existing ones.

I don't want to sound negative - I'm sure everyone would welcome ideas
on how to improve the documentation - but adding comments would mean
you would have to store them somewhere, which would mean someone would
have to administer that, plus the anti-spam logins etc. And who would
maintain them? One of the main problems with the existing docs is that
much of it was written long ago and is at least partly out-of-date.
Comments would age too.