SPAM: Re: [mapserver-dev] Documentation updates

[Josh Livni]

I can see that a trac/svn solution would be better for a number of 
reasons, not the least of which being more folks have familiarity with 
the infrastructure than with Plone.  And maybe worse for something 
things (searching?).

However, if it turns out that for various reasons there is interest in 
sticking with Plone for the docs, I am willing to volunteer to at least 
research
1) difficulty in upgrading to Plone v3 (which has some better versioning 
opportunities)
2) integrating a more robust workflow in Plone Help Center (and seeing 
if any customizations to it would make it hard to easily migrate to 
Plone 3)
3) working to get more caching in for anonymous users (faster pageload 
times)

Assuming none of the above turns out to look completely crazy to 
implement, I'm willing to do that as well.

But, as Howard noted on IRC just now, replacing him with someone else 
hardly solves the key issue of the general devs being able to maintain 
the docs infrastructure without too much hassle of learning new stuff.   
So, that all said - if folks publicly say that the Plone path _should_ 
be continued on, then I'll be happy to begin working on the above in a 
few weeks from now.

Cheers,

 -Josh

Howard Butler wrote:

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
_______________________________________________
mapserver-dev mailing list
mapserver-dev at lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
> dev