[mapserver-dev] Versioned MapServer Docs?

[Even Rouault]

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.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20210318/842c2e25/attachment.html>