[OpenLayers-Dev] Additional Documentation

[Howard Butler]

On Nov 13, 2008, at 8:01 AM, Christopher Schmidt wrote:
>
> For the record, I see this as being somewhat similar to the
> Plone/MapServer situation, where Jeff and Howard are trying to move  
> away
> from managing the docs thrugh Plone and instead manage thrugh SVN. In
> theory, managing through Plone offered great benefits for allowing the
> community to contribute -- but in practice, it's just a pain in the
> keyster.

Yes, we (MapServer's documentation effort) is looking to copy a lot of  
what OpenLayers does for documentation currently.  A community   
website like Plone ends up taking way too much administrative effort,  
and the lack of administrative manpower has been one of the great  
limiting factors of the MapServer website.  We're moving away from  
Plone and to just using rst and svn because users contribute  
practically zero documentation, and the Plone site ends up just being  
in the way of the developers/documenters.  There's always the wiki  
where a user can drop tidbits of info that can eventually be folded  
into regular documentation.

I would argue that in comparison to the 1.0 MapServer website, the  
current one was moderately successful in its organization, quite  
successful in the migration of the docs from docbook to rst,  and a  
complete and utter failure as a community website.  A wiki is  
insufficient for the reasons that Chris outlined, but a giant do-all  
site like MapServer's current one would end up failing without the  
manpower to make it go.  I think the happy medium is a static website  
with the content driven from svn, and a spam-protected wiki that users  
can garden for information that needs to migrate its way into the  
docs.  MapServer's infrastructure was *almost* this before the current  
incarnation except for:

- docbook was a giant hurdle for people to write docs
- our wiki gathered way too much spam (this was before captcha, etc  
became popular and OSGeo came along with enough momentum to make a  
single sign-on worth the hassle)
- cvs made branching and tagging fun!

We (mostly I, but others helped ;) swung the pendulum too far past the  
mark, but eventually we'll oscillate to it.

Howard