[OpenLayers-Dev] [OpenLayers-Users] OpenLayers Book

[Christopher Schmidt]

(Moved from the talk list because I think it's less relevant than the
rest of the thread.)

On Tue, Jan 13, 2009 at 02:01:41PM -0700, Tim Schaub wrote:
> I think this is a good idea.  As with other ideas, it will take someone 
> to organize things, generate interest, bug people for money, etc. to get 
> anything done.
> 
> I don't think we should take it upon ourselves to waste beautiful 
> Saturdays generating documentation for free (person opinion).

Oh, I'm sorry. I'll stop that, then. :p

More seriously, how can you imagine this working in any other way? If
there's a $500 sponsorship to OL through OSGeo, how do you see that
money being spent such that it creates documentation?

Right now, I see no one as being interested in doing documentation work,
and I don't consider it the highest priority for OpenLayers. For
example, if I were to fund someone to do work, I would be spending the
money on merging the WFS sandbox into trunk -- something that we delayed
the 2.7 release for, and now, several months later, still isn't in
trunk. We now have half a dozen or more users off in a branch that's
not being maintained by at least some of the core developers, and at
this point, no timeline for when this branch will be merged. This type
of situation -- actively encouraged by many mailing list posts from
users and developers of the code -- has created a situation where we
have divergent development codebases, something that can't be beneficial
for the project. 

I do not consider the documentation we currently have available to be
worth the money it would cost to create it, versus spending it on other
things.

Speaking as a PSC member, I am unwilling to pay PSC members for
OpenLayers activities. As such, my time on OpenLayers can't be purchased;
working on it in my free time is the only alternative I can see to not
working on it at all. (Of course, if my working on it is setting a bad
precedent, and discouraging investment in the project, I'll accept that
opinion and limit my paticipation, though I can't promise I'll stop.) 

I understand that some OpenLayers developers work at organizations which
support their work, which the OpenLayers might be able to pay for their
time. Thus far, I have not seen any direct commitment to any OpenLayers 
documentation effort from any such organization , and I don't expect
that organizations which are not supportive of documenting OpenLayers
are suddenly going to change their priorities due to an amount as small
as $500. (OpenGeo has done significant work on documentation, but nothing
about that work appears to be 'altruistic' or for the good of the
OpenLayers project, and instead appears designed to support OpenGeo's
efforts. This isn't unreasonable, but doesn't speak to me as an
indication that OpenGeo -- as an example -- is in the business of
supporting a potential OpenLayers documentation effort, even in response
to accepting sponsorship cash.) 

Now, I think there is a clear possible solution to the documentation
problem: that is, making documentation work a priority for the project.
If it was really the case that we felt that documentation was more
important than refactoring, or fixing bugs, or answering mail on the
mailing list, then we -- OpenLayers developers -- would work on
documentation in place of these things. 

The fact that no one else is doing this simply says to me that t most of
the contributors to the project, this is *not* the most important task,
but is secondary. To me, this *is* more important, because I tend to
answer the same questions over and over again, and in doing so, I waste
my time and eeryone else's, so I make writing documentation a priority.   

If developers want to commit to documentation as a priority, I think
that the answer is simple: establish it as a priority above other tasks,
whether that be dealing with the mailing list, working on new features,
or creating OpenLayers 3.0. A documentation sprint probably -- in the
end -- clears up a lot more developer hours than a potential OpenLayers
3.0 does, simply by the nature of the fact that a lot of the developer
interaction to create a successful proect right now centers around
explaining the same things again and again. If there is motivation to
change that, now seems like the time. 

In the meantime -- unless my contributions on my free time are seen as
detrimental to the project -- I'm going to keep working on
documentation on Saturday mornings.

Best Regards,
-- 
Christopher Schmidt
MetaCarta