[OpenLayers-Dev] OL Documentation Improvement

[Christopher Schmidt]

On Fri, May 04, 2012 at 07:28:10AM -0400, Jesse V. Griffis wrote:
> 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.

Pushing any of the OpenLayers docs online does not seem like it would be
beneficial to me.

The developer docs (API docs) are arguably where we need the most help.
Maintaining those anywhere other than the code is completely impractical.
(Maintaining them *with* the code is almost impractical.) Doing what PHP
does for our API documentation would simply not work.

Also note that PHP documentation is not 'maintained' in a CMS; it is 
maintained in docbook format, and translated into a website by various
PHP tools. Writing these tools for OpenLayers is possible, but time
consuming; they would also need to constantly be run as we update the
code and corresponding documentation, etc.

As far as the docs.openlayers.org prose documentation: I don't think that
anyone would benefit from having those in any kind of CMS. I realize the
value of comments, but I don't think it overrules the value of making
the documentation something that someone feels ownership over.

Admittedly, none of our prose documentation has ever been studiously
maintained as much as I had hoped it would be when I set it up, but it
is still the case that I don't believe that documentation-in-a-CMS really
ever works -- I've seen no evidence to support that, and a bunch of 
counter points. (An obvious one in the OSGeo world: MapServer, which 
switched from CMS to non-CMS and had way more developers putting effort
into documentation and translation.)

> 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).

The 'hard'ness isn't just dropping things into a CMS, no, but that's not
what any reasonable documentation approach would involve :)

Best Regards,
-- 
Christopher Schmidt
Web Developer