[OpenLayers-Users] OpenLayers Book

[David Fawcett]

Mika,

I think that you have pointed out the significant challenge for grass
roots generated documentation for a quickly changing project like
OpenLayers.  Most of us who post questions to the list do not have
enough knowledge of OpenLayers to write large parts of the
documentation.  (Definitely don't mistake me for someone who knows a
lot about OpenLayers...)  It often feels like I am reverse compiling
the code and examples.

It sounds like we are also in similar situations with life, young
kids, etc.  I think that the key is that if one wants to contribute to
the project, as you learn something new, or create an example, if the
functionality isn't in the documentation yet, take a little bit of
time to add/submit it.  I have contributed a fair amount of
documentation/examples for the MapServer project.  Often times, when I
figured out how to do something new, I would submit it so someone else
didn't have to spend the time discovering the same thing.  Hopefully I
can start doing the same thing for OpenLayers as time allows and as I
learn more about the library.

To me, an area of documentation that would be very useful would be the
higher level stuff.  (e.g. What are the current best practices?
[vector layer with markers vs. marker layer] , How do all of these
contexts, strategies, etc. fit together and when would you use them?)
I can often/sometimes hack something together that works, but is it
really the best way to do it?

David.



On Wed, Jan 14, 2009 at 1:03 AM, Lehtonen, Mika <mika at digikartta.net> wrote:
> I agree on financing model, absolutely. Making the access subscription
> based, in my opinion, would break the open source principle. But who would
> write the documentation? I have been noticing that the deeper you get in any
> thing, less you know what's happening on the surface. Are all the user-list
> members competent on writing documents (or code)? No they're not, at least
> I'm not. On the other hand who knows the most of the code? I think it's
> he/she who wrote it.
>
> I am 38 and started learning programming as a hobby when I was 35. Now I am
> getting my bread and butter of it. It's not so easy to learn any more in
> this age + kids + wife + life. Still, I have thought this open source issue
> so, that one day I will start contributing to the community. Until that
> time, I will be a party that gets more than gives. So people who have got
> deep should understand that they can't assume that everyone in the users
> list are able to write documentation and code. Why would we ask simple
> questions, if we were competent on writing documentation on our own?
>
> I personally like PostGIS documentation [
> http://postgis.refractions.net/documentation/ ]. Could OpenLayers
> documentation be like it? For those who prefer more printed documentation,
> could be published e.g. PDF-versions, right? And if the format and the
> layout is proper, it's not so expensive to make some printing office to
> print books even the number of them would be small. They have digital
> printing presses nowadays.
>
> - mika -
>
> David Fawcett kirjoitti:
>>
>> I would be happy to kick in $25 - $50 to support the production of
>> documentation.  Instead of making access to documentation subject to a
>> donation, I would rather have any donation money leveraged by making
>> more documentation available to as many people as possible.  People
>> who have never used OpenLayers, people looking for a new solution,
>> etc.  Evangelism vs subscription.
>>
>> I understand what Chris is saying.  Some people get off on coding and
>> are willing to spend their personal time writing code for a project
>> that they think is worth while.  These same people may not find the
>> same pleasure in writing documentation.  (not many people do...)
>>
>> I think that the key to grass roots documentation development is to
>> encourage people who are OpenLayers users who are not core developers,
>> who want to give something back to the project to write documentation.
>>  While it would be cool to have a paper book, it would start to become
>> out of date as soon as it was published.  The same amount of resources
>> and time, contributed by a larger group of people, could create (and
>> maintain) some really great web-based documentation.
>>
>> David.
>>
>