[mapserver-dev] Documentation updates

[Howard Butler]

On Mar 5, 2008, at 5:05 PM, Steve Lime wrote:

> Personally I'd favor one set of docs, with notes where applicable  
> about version specific issues. If there are
> big changes in one area then perhaps it would be necessary to have a  
> version specific document but that's
> relatively rare. Most things tend to be quite stable. Having a  
> single "MapFile Reference" would be a lot
> easier to maintain. Just a thought...


I'm of the opinion that our official docs belong in svn.  I think it  
is clear that the Plone site has been a failure with respect to  
collecting user contributions.  I think there are numerous reasons for  
this:
- You still need credentials to have full reign on the docs, meaning  
you have to jump over a bar to get someone (usually me or Jeff) to  
give you permission to do what you need.  Only devs and Jeff really  
contribute substantially to the docs.  Our document workflow should be  
arranged to accommodate this fact.
- Editing text files through a web browser sucks.
- Our Plone site is freaking slow.
- We don't have a clean way of keeping docs versioned (making it  
easier to do nothing than to jump into the tar pit)
- The Gallery is a freaking mess.
- We have no way to snapshot docs with releases

Each of these issues could be overcome by a Plone admin willing to  
dump a lot of time into it.  Plone admins must be making too much  
money as consultants, because none ever show up to help with the  
MapServer website, however ;)  Without some more manpower, our Plone  
site is not our future.  Or at least, it is not our shiny, happy  
future.  The upkeep, care, and customization required to get it to do  
what we want is too much for one person on volunteer time to deal with.

One area that I do think was successful was Sean introducing us to  
reStructured text.  Jeff and I have converted most of the docs in the  
Plone site to restructured text which has made for easier editing  
(among other things).  reStructured text can be used in Trac and Plone  
(heck, there's even a Java parser available for it).  You can edit it  
with vi or emacs without wading through gobs of tags (unlike DocBook),  
but you still have the transformation options available to you (to  
HTML,  to PDF, to man pages, etc).

Other successes of the Plone site in my opinion include:
- thank god for searching
- document linking and navigation is more straightforward
- organization is arguably better than the "blue" site was

MapServer's Trac instance, on the other hand, already has more than  
one admin available to it, and it also has the advantage of being  
under OSGeo's umbrella, meaning that collective maintenance of all of  
the OSGeo projects' bug trackers eliminates a lot of administrative  
duplication.  For example, Frank or I fixing GDAL's Trac or adding  
features to it means that it is quite trivial to drop that into  
MapServer's Trac.

When I started in on the Plone site, I was very much against the wiki  
concept because I had seen what a mess it had turned into for  
MapServer.  The spammers moved in and planted their dirty asses  
there.  We didn't have enough editors or community folks "keeping up  
the garden" and stuff quickly devolved into spammed-to-death dreck.   
If we were to move everything to our Trac instance, I don't think this  
would be the case, however.  First, MapServer's community has grown  
quite significantly since then -- maybe we can guilt more folks into  
editing :).  Second, OSGeo has a strong incentive to keep spam off  
their site for all of the projects -- collective administration again  
helps us.

I still think wikis make for awful primary software documentation, but  
I'll admit that they're a generally good way to *collect* it.  For the  
concept to work well for software documentation, in my opinion, you  
need to have gardeners go through at release time, pull the useful,  
new, and best stuff into the actual docs and nuke the crap that's out  
of date, doesn't make sense, or is so incomplete it is likely to  
confuse.  We don't really have a history of doing something like that  
though.

So, we're at a fork in the road.  We could keep the Plone site, just  
as it is, and suffer through it, just as we have.  More Plone admins  
could magically appear from thin air and fix the problems we have with  
our current site and take it to the next level (I am not this guy).   
We could dump the official docs like the WMS HowTo, etc into SVN and  
then hook them up to Trac wiki pages for user contribution (loosing a  
lot of the good things we have in the Plone site in the process).

Where do we go?

Howard