[Lexicon] Semantic versioning standard for documents?

[Cameron Shorter]

Thanks for the additional info Scott.
I hadn't considered that some organizations (you mention ISO) only
maintain one baseline version, and deprecate previous versions.

Looping in: +Ronald Tse <tse at ribose.com>, +Reese W. Plews <rplews at gmail.com>
and our public  glossary email list +lexicon <lexicon at lists.osgeo.org> which
contains all the looped in participants.

On Tue, Jan 4, 2022 at 5:51 AM Scott Simmons <ssimmons at ogc.org> wrote:

> Hi Cameron,
>
> I would like to see more standards for document content and versioning as
> everything is pretty loose and I feel that many organizations have to make
> up their own rules (or copy rules from others). I think that we have two
> end-member states: (1) versioned documents such as OGC, OMG, IHO, etc.
> Standards and (2) non-versioned documents such as ISO Standards.
>
> The versioned community generally has some concept of significance of the
> version and accommodation of backward compatibility. OGC and IHO are very
> strict in the rules and conventions. Multiple versions may be supported at
> one time (especially with OGC).
>
> The non-versioned community treats each new edition as independent of the
> old and usually deprecates the older version. ISO makes no promises of
> backward compatibility and I do not think that there is a rule that
> requires that differences between publications be documented.
>
> So, yes, OGC would be happy to submit our rules to be part of a larger
> document versioning Standard. We’d even be happy to reference such a
> Standard as normative if it mostly agrees with our current rule set.
>
> I think that we should loop Ron Tse into this conversation as his work on
> content management and model-driven Standards would allow for more
> quantitative measure of the degree in change between versions.
>
> Best Regards,
> Scott
>
> On Dec 31, 2021, at 12:21 PM, Cameron Shorter <shortcam at google.com> wrote:
>
> Thanks for the feedback Scott,
> I've added a link to your directive 18 from the Further Reading section.
> Would there be value in moving OGC's directive 18 toward a community wide
> Semantic Versioning for Docs standard. How would this be approached? Is
> there a lightweight review process that OGC members could be invited to
> take part in?
>
> Do you know of a person or group within ISO and/or IEEE who would be worth
> reaching out to with a similar message?
>
> On Fri, Dec 31, 2021 at 8:47 AM Scott Simmons <ssimmons at ogc.org> wrote:
>
>> Hi Cameron,
>>
>> I am not aware of document-specific versioning conventions and we
>> generally use SemVer in OGC. The only OGC documents that are versioned are
>> Standards or Best Practices and since those are really just written
>> specifications, SemVer is appropriate. Our own versioning policy is Policy
>> Directive 18 here:
>> https://portal.ogc.org/public_ogc/directives/directives.php
>>
>> I think that your document-centric version makes a lot of sense. Given
>> that even technical documentation does not always have the consideration of
>> “backward compatibility,” I wonder if there is another term that may be
>> more appropriate. Is a minor version only appropriate when documenting
>> something which itself has minor versioning?
>>
>> Best Regards,
>> Scott
>>
>> On Dec 22, 2021, at 1:48 PM, Cameron Shorter <shortcam at google.com> wrote:
>>
>> Hi Scott,
>> Are you aware of published semantic versioning standards or conventions
>> which are applied to documentation? (Specifications are one variant of such
>> standards.)
>>
>> I have a need for documentation semantic versioning for two projects I'm
>> involved in:
>> 1. For specifications I'm drafting at Google.
>> 2. For documentation templates we are developing within The Good Docs
>> Project <https://thegooddocsproject.dev/>. (Doc templates for open
>> source.)
>>
>> We've drafted a possible semantic versioning addendum for documents
>> <https://docs.google.com/document/d/1gPr_OHoUkg5Wjj3UWYX78ORtTBArSJck4mWrKhWpfPA>,
>> and are looking for:
>> * Pointers to any related initiatives which we could defer to if they
>> exist.
>> * Introductions to people who might be interested in filling this space.
>> (Feel free to forward this email.)
>> * Feedback on our proposal. (Feel free to add comments.)
>>
>> Cheers,
>>
>> --
>> Cameron Shorter,
>> Technical Writer, ChromeOS Platforms
>>
>>
>>
>>
>> Sign up for OGC News
>> <https://ogc.us4.list-manage.com/subscribe?u=704e02f81107a6caab1568067&id=4e4528fd9d>
>>
>
>
>
> Sign up for OGC News
> <https://ogc.us4.list-manage.com/subscribe?u=704e02f81107a6caab1568067&id=4e4528fd9d>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/lexicon/attachments/20220104/16058b6f/attachment.html>