Re: Naming conventions for committee notes

Hi Kris and all,

While we sympathize with theÂTC's intention of using a title which best represents the Committee Note's contents, we don't have any flexibility regarding the presence of "Version x.y" at the end of the title.

- It drives the structureÂof the URIs used to publish all the documents in the OASIS Library (docs.oasis-open.org) (e.g., "Version 1.0" yields "v1.0", which appears twice in every URI)

- It's required by the Naming Directives approved by the board of directors - see http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#Version

Keep in mind that the "Abstract" text on the front page will provide an immediate way to clarify any ambiguities due to the title. The introduction section will also provide a good place to elaborate.

Although my personal opinion has no bearing onÂ a matter forÂthe TC's decision, I'll add:

Of the three titles you've listed, I think "Using DITA Troubleshooting Version 1.0" is the strongest candidate. Anyone interested in the topic would be drawn to the title, and the Abstract can help them verify whether it applies to their Version of DITA. The title would also be applicable to possible later Versions of DITA withoutÂany changes other than issuing a new Committee Note in the sequence.

However, I think I've previously pointed out two OASIS TCs which followed the other two models you've presented:

- the XACML TC published "XACML 3.0 Additional Combining Algorithms Profile Version 1.0" (http://docs.oasis-open.org/xacml/xacml-3.0-combalgs/v1.0/cs01/xacml-3.0-combalgs-v1.0-cs01.html), as well as "XACML v3.0 Related and Nested Entities Profile Version 1.0" and "XACML v3.0 Time Extensions Version 1.0"

- the OData TC has a main specification at Version 4.01, and they've chosen to apply that number to several other specifications which tie into it,Âeven though they did not pass through v1.0, v2.0, v3.0, etc.. See for instance OData JSON Format Version 4.01 (https://docs.oasis-open.org/odata/odata-json-format/v4.01/os/odata-json-format-v4.01-os.html), where the "Related work" on the front page shows several of those co-numbered specifications.

I'm sorry to not be able to accommodate the TC's request for eliminating the Version from the title, but it really is integrated into the entire OASIS publication model.

Best regards,

Paul (for Chet - on vacation this week)

On Wed, Sep 22, 2021 at 5:08 AM Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

Hi, Chet and Paul.

The DITA TC wants to raise some questions/points about naming conventions for committee notes. They arose as we discussed the best title for our forthcoming committee note about using DITA 2.0 for troubleshooting.

As we understand it, OASIS wants us to use the following conventions for the committee note (cn) title and numbering of the cn:

<Committee-note-title> Version X.0

Begins at cn01, is moved to cn02 for a subsequent approved and published document

This presents some issues for us in regard to naming the troubleshooting committee note. We discussed the following possibilities:

Using DITA Troubleshooting Version 1.0

Problem: The cn strictly is about the troubleshooting features offered with DITA 2.0, not DITA 1.0.

Using DITA 2.0 Troubleshooting Version 1.0

Problem: Technically accurate, but possibly confusing. Is the cn about DITA 1.0 or DITA 2.0?

Using DITA Troubleshooting Version 2.0

Problem: Confusing, as this will be the first version of the committee note.

Can we drop the Version X.0 from the title? It seems unnecessary, especially if the cn<number> indicates the "version" of the document.

If we could do that, we'd name the cn "Using DITA 2.0 Troubleshooting" or simply "Using DITA Troubleshooting."

--
Best,
Kris

Paul Knight

Document Process

OASIS Open

+1 781-883-1783

paul.knight@oasis-open.org

dita message

Paul Knight