[mapserver-dev] Versioned MapServer Docs?

[Jeff McKenna]

As a user I'm constantly relying on those 'added in 5.0' notes, this is 
the information that a user needs and craves in the actual user document 
(not separate deep in an RFC document).  I see these version notes (a 
single line that is nicely color coded often) as always relevant, as 
users need to know when a parameter was added (and especially those ones 
that aren't always fresh & mentioned, such as old 5.0 ones etc).

-jeff





On 2021-03-18 7:23 p.m., Even Rouault wrote:
> My point was too much (no longer relevant) information kills 
> information. For the user of Mapserver 7.6, what's the point in seeing 
> some feature was added in 4.0 or removed in 5.2 ? That just adds to the 
> cognitive load. It might be useful though to see that something was 
> added / removed recently and you don't benefit yet from it or are 
> dependent on it.
> 
> Le 18/03/2021 à 23:17, Richard Greenwood a écrit :
>> As a guy who has been reading the mapserv docs for 20+ years I'll say 
>> that I love the format of the docs in general and specifically the 
>> version added, version deprecated, etc. Thanks Jeff and all the other 
>> contributors. Hopefully I'll be reading the docs for another 20 years.
>>
>> Rich
>>
>>
>> On Thu, Mar 18, 2021 at 3:18 PM Jeff McKenna 
>> <jmckenna at gatewaygeomatics.com <mailto:jmckenna at gatewaygeomatics.com>> 
>> wrote:
>>
>>     Ah ok Even, your words sunk into me more now, good points. 
>>     Although I
>>     differ in that I think keeping all of the 'versionadded'
>>     references are
>>     very important, as this is the rich information that is so priceless
>>     (knowing when exactly something was added) for both the users and
>>     maintainers of the software/docs.  I personally have been making
>>     sure to
>>     add those 'versionadded' and 'deprecated since' and 'since version'
>>     notes into the docs, as this information is so useful to users,
>>     even in
>>     the case of it being added in 5.0 etc.  And as you said, I have to go
>>     get that information in the RFC, which users won't know to check, so
>>     I've been adding those 'since version' references that you
>>     mention, to
>>     help users.
>>
>>     -jeff
>>
>>
>>
>>     On 2021-03-18 5:39 p.m., Even Rouault wrote:
>>     > If we keep a single version for simplicity, we could however
>>     decide to
>>     > clean up a bit the doc content to remove mentions of outdated
>>     versions
>>     > to avoid cluttering it. There is little point in mentioning any
>>     version
>>     > older than let's say 5? years ago. I've done that a bit in the
>>     GDAL docs
>>     > a few months ago, removing any mention of GDAL < 2, considering
>>     that all
>>     > people looking at the docs would have at least GDAL 2.x something
>>     > available, or if they use antiquated stuff, too bad for them.
>>     >
>>     > Looking a bit at download artifacts, for MapServer we could
>>     decide for
>>     > example that the baseline is MapServer 6.4 (or possibly even 7.0
>>     for
>>     > simplicity), and remove any mention of that or older versions
>>     (except in
>>     > RFCs that are reflective of history)
>>     >
>>     > "grep -r versionadded en" in the doc repository shows a number
>>     of things
>>     > of the 4.x, 5.x or early 6.x eras.  'grep -ri "since version"
>>     en' shows
>>     > also a number of potential cleanups.
>>     >
>>     > Even
>>     >
>>     > Le 18/03/2021 à 21:15, Jeff McKenna a écrit :
>>     >> My preference has always been for Option#1, as it is much
>>     easier to
>>     >> maintain in my experience, as it is stated clearly as
>>     deprecated at
>>     >> the parameter level in the document.
>>     >>
>>     >> Speaking openly here, if I was paid fulltime to manage the docs
>>     and
>>     >> all the different build versions of the docs, and publishing them
>>     >> online, I could see how that would be possible; but as we are
>>     made up
>>     >> of volunteers, I would prefer to keep the single version
>>     updated with
>>     >> references to when the feature was added (what MapServer
>>     version), and
>>     >> if it is deprecated.  I remember recently spending much effort
>>     on that
>>     >> in-line versioning improvements, I think that is working nicely
>>     now.
>>     >>
>>     >> -jeff
>>     >>
>>     >>
>>     >>
>>     >>
>>
>>
>>     -- 
>>     Jeff McKenna
>>     GatewayGeo: Developers of MS4W, MapServer Consulting and Training
>>     co-founder of FOSS4G
>>     http://gatewaygeo.com/ <http://gatewaygeo.com/>
>>     _______________________________________________
>>     mapserver-dev mailing list
>>     mapserver-dev at lists.osgeo.org <mailto:mapserver-dev at lists.osgeo.org>
>>     https://lists.osgeo.org/mailman/listinfo/mapserver-dev
>>     <https://lists.osgeo.org/mailman/listinfo/mapserver-dev>
>>
>>
>>
>> -- 
>> Richard W. Greenwood, PLS
>> www.greenwoodmap.com <http://www.greenwoodmap.com>
>>
>> _______________________________________________
>> mapserver-dev mailing list
>> mapserver-dev at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
> 
> -- 
> http://www.spatialys.com
> My software is free, but my time generally not.
> 
> 
> _______________________________________________
> mapserver-dev mailing list
> mapserver-dev at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
> 


-- 
Jeff McKenna
GatewayGeo: Developers of MS4W, MapServer Consulting and Training
co-founder of FOSS4G
http://gatewaygeo.com/