[OpenLayers-Dev] OL Documentation Improvement

[Christopher Schmidt]

On Thu, May 03, 2012 at 11:13:48PM -0700, Keith Moss wrote:
> Hi all,
> 
> I hope this is an appropriate topic for the -dev list and my apologies if
> it's not.
> 
> 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.

The problem with doing this isn't that it would be a bad idea -- allowing
user comments or edits to the documentation more easily would be cool -- 
but instead that it is technically difficult, because of how our documentation
works.

Our documentation exists only as a set of static files; although there are
ways I can think to add comments to these things, they all require a non-trivial
amount of investment into what are some pretty gnarly tools.

It is somewhat easy these days to offer minor fixes to the documentation, since
all the documentation is available in Github -- this means that it's possible
to propose changes (via pull requests) directly via the browser, which is 
somewhat helpful hopefully, though I realize that isn't really obvious from
the documentation itself (and making it more obvious would probably be
easier than adding comments).

If you have thoughts on how this should be implemented, I'd be interested
in hearing them; certainly, I wanted user comments a couple years ago :)
I just don't know how to get them easily.

Best Regards,
-- 
Christopher Schmidt
Web Developer