On Wed, Apr 24, 2013 at 11:44 AM, Jonathan Moules <
[email protected]> wrote:
> Hi Andrea,
> I wasn't aware of this (I have a couple of "issues" open relating to the
> documentation) - it may be worth posting to the user-list too.
>
> I suspect having the docs in git makes them significantly less accessible
> than a more conventional wiki, which may explain the lower participation
> from non-developers. Almost everyone can figure out how to use a wiki in a
> couple of minutes, but to do the GeoServer docs you need extraneous
> software (git, or gitextensions for a GUI), an understanding of version
> control, something that can transcribe ".rst" files (I'd never encountered
> them before) *and* the willingness/knowledge to actually update the
> documentation.
> I'm not saying to convert the documents to a wiki (research* suggests
> that'd be a bad idea), but you can see how one of these has a much larger
> barrier to entry than the other.
>
Actually the GeoServer documentation was originally in a wiki, we switched
away because of several issues:
* no one from the user base was contributing anyways
* the documentation would get spammed regularly
* we could not maintain a per version documentation, so new features
available only on trunk were documented on the only documentation we had,
and people got confused
* editing long documents in the wiki was a real issue, connection drops
resulted in good half hours of work getting lost
Other projects went through the same ordeal and eventually made the same
move and yet they do have non developers contributing to the docs (e.g.,
MapServer).
>
> * - the Research alluded to is a fascinating paper titled "Creating and
> evolving developer documentation: understanding the decisions of open
> source contributors" -
> http://cs.queensu.ca/~ahmed/home/teaching/CISC880/F11/papers/Documentation_FSE2010.pdf
> It does a comparison of documentation contribution issues for 19 documents
> for Open Source projects. I'd suggest giving it a read - there are probably
> lessons in there for how to increase community participation that could
> help GeoServer.
>
Nice, I'll have a look
Cheers
Andrea
--
==
GeoServer training in Milan, 6th & 7th June 2013! Visit
http://geoserver.geo-solutions.it for more information.
==
Ing. Andrea Aime
@geowolf
Technical Lead
GeoSolutions S.A.S.
Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy
phone: +39 0584 962313
fax: +39 0584 1660272
mob: +39 339 8844549
http://www.geo-solutions.it
http://twitter.com/geosolutions_it
-------------------------------------------------------
------------------------------------------------------------------------------
Try New Relic Now & We'll Send You this Cool Shirt
New Relic is the only SaaS-based application performance monitoring service
that delivers powerful full stack analytics. Optimize and monitor your
browser, app, & servers with just a few lines of code. Try New Relic
and get this awesome Nerd Life shirt! http://p.sf.net/sfu/newrelic_d2d_apr
_______________________________________________
Geoserver-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
