[OpenLayers-Dev] OL Documentation Improvement

[Jesse V. Griffis]

On Friday, May 04, 2012 07:10:36 AM Christopher Schmidt wrote:
> 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.

Maybe I'm jumping in out of turn here and for that I apologize, but why wasn't 
it pushed online ages ago? User comments (as those done on the php docs) can 
save innumerable hours searching through mailing lists.

It can't be that hard to munge text from 'static files' and do a one-time 
import into some CMS (drupal or wordpress come to mind, but it really doesn't 
matter).

Jesse

-- 
Jesse V Griffis
Senior Developer
NBT Solutions LLC
Buffalo, NY
phone: 716.210.6092
email: jesse.griffis at nbtsolutions.com
web: www.nbtsolutions.com