[mapserver-dev] Re: RFCs

[Howard Butler]

On Dec 1, 2008, at 11:29 AM, Bob Basques wrote:

> Nice stuff this conversion of the Doc's.
>
> I'm wondering if now is the time to suggest this (or not :c).  Has  
> any thought been given to the idea of integrating MapServer Doc's  
> with other Frontend applications documentation?
>

By frontends, do you mean OpenLayers, and Ka-map, and GeoMoose, etc?

> I've used a few different MapServer Frontends in the past and the  
> biggest stumbling block for new users is the documentation for  
> MapServer and the Documentation for the front end being  
> disconnected.  What applies to MapServer, and what applies to the  
> frontend.

One of the things that the MapServer.pdf showed me is just *how much*  
documentation we already have.  In the context of browsing on the web,  
you don't really notice it, but it's nearly 800 pages!  I think we do  
need to focus more on introductory stuff, however, but no developer is  
rightly equipped to be writing that.  Things like http://iowa.hobu.biz/msdocs/build/html/new_users.html 
  need to be fully fleshed out and put in context with the frontends  
that you're referring to.  Examples and tutorials and integration case  
studies need to be developed and/or extended.  All of this stuff is  
hard work with little reward.  Maybe there will be opportunity for  
more of this to grow once we move the Plone site roadblock out of the  
way.

>
>
> One thought I had early on, was to harvest the MapServer Doc's and  
> add to them for the appropriate frontend.
> on the surface, this seemed like a good approach, but I'm having  
> second thoughts about it now.

Right, because forking the docs like this means having to take on  
responsibility for maintaining them forever.  It might be more  
productive to start contributing to the existing docs to fill in what  
you see as deficiencies ;)

> Another aspect (or problem) was when someone wanted to try adding a  
> front end to an existing MapServer Install, a Good separation of  
> Doc's by versions would be something nice to add for this purpose,  
> this could be as simple as building a snapshot before MapServer  
> upgrades are released. A versioned release of the Doc's with the  
> MapServer release would be a simple step in this direction.

That is the intent with this effort.  Docs will be kept in subversion  
and snapshotted with releases.

>
>
> I know this is all piddly stuff in the scheme of things, but making  
> the Doc's easier to interpret helps out everything in the end.
>
> bobb
>
>>>> Howard Butler <hobu.inc at gmail.com> 12/01/08 11:12 AM >>>
>
> On Nov 27, 2008, at 9:13 AM, Howard Butler wrote:
>
>> All,
>>
>> This is a notice to let you know that all RFCs are to be edited from/
>> within subversion, and not on the Plone site.  Additionally, while
>> reviewing the RFCs and tweaking the ReStructured text, I noticed
>> there were a number of them that had no status information, or did
>> not state which version of the software they were implemented for.
>> We probably need some sort of styling document describing the
>> terminology and protocol for RFCs, but I'd hate to write an RFC on
>> how to write an RFC ;)
>>
>> http://svn.osgeo.org/mapserver/trunk/docs/development/rfc/
>>
>> Howard
>
> Here's 2.8 mb of MapServer documentation goodness :)
>
> http://iowa.hobu.biz/MapServer.pdf
>
> 739 pages, doesn't have any TOC or indexes yet, but should give you an
> idea where things are going.   After some consideration, I decided the
> ability to cross reference the RFCs made having them in subversion
> more valuable than having them in trac.
>
> http://iowa.hobu.biz/msdocs/build/html/index.html still for HTML
> version.
>
>
>
>
> _______________________________________________
> mapserver-dev mailing list
> mapserver-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapserver-dev
>