[mapserver-dev] Versioned MapServer Docs?
Jeff McKenna
jmckenna at gatewaygeomatics.com
Thu Mar 18 16:25:14 PDT 2021
I also think here we have a difference between how a core developer
works (on main, building from source) and then how a typical software
user works (using a binary/package built by someone else, often a much
older MapServer version), so those one-line notes of version added
(which is absolutely irrelevant to a core developer who uses the latest
source each day) become what I would call a total "lifeline" to a user,
so they can know what parameters work with their old installed package.
-jeff
On 2021-03-18 8:18 p.m., Jeff McKenna wrote:
> 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/
More information about the mapserver-dev
mailing list