Re: [Openchain-Specification] OpenChain Specification 2.0 - Formatting for ISO - RFC


Oliver Fendt
 

Hi

 

I have made some minor comments in the document Rex distributed.

 

 

Ciao

Oliver

 

Von: openchain-bounces@... <openchain-bounces@...> Im Auftrag von Rex Jaeschke
Gesendet: Donnerstag, 25. Juli 2019 17:14
An: 'Shane Coughlan' <coughlan@...>; 'Alexios Zavras' <alexios.zavras@...>; 'Indira' <indira.bhatt@...>; 'Mark Gisi' <mark.gisi@...>
Cc: openchain@...; Openchain-specification@...; 'Alexandra Boehm' <aleksa.boehm@...>
Betreff: Re: [OpenChain] [Openchain-Specification] OpenChain Specification 2.0 - Formatting for ISO - RFC

 

Re Terms and definitions:

 

According to the ISO Style Guide:

 

Terms shall be written in lower case characters. Upper case characters, mathematical symbols, typographical signs and syntactic signs (e.g. punctuation marks, hyphens, parentheses, square brackets and other connectors or delimiters) as well as their character styles (i.e. fonts and bold, italic, bold italic, or other style conventions) shall be used in a term only if they constitute part of the normal written form of the term. Terms shall in general be presented in their basic grammatical form, i.e. nouns in the singular, verbs in the infinitive.”

 

And that is the style I changed to. Basically, a reader needs to be aware of all the terms defined up-front without there being any emphasis device to highlight term usage.

 

 

Re Combining the requirements into a single clause (which is how you originally presented it)

 

That’s fine with me. I just changed to that format; see the attached revision.

 

 

Re third-level numbers

 

I believe you are asking for all the items in “Verification Material(s)” to have their numbers restored, as in 1.1.1, 1.1.2, …

I’m fine with that; clearly I misunderstood the importance of these numbers as unique IDs.

 

I note that the numbers in your original spec are hard-coded. My first instinct is to have them be automatically generated, but on reflection, that is not a good idea, as the item numbering would automatically (and quietly) change if the document structure was changed, rendering external pointers into this spec to be invalid.

 

In the attached revision, for the first list only, I’ve shown 3 alternative formats: a solid circle bullet + number, a solid square bullet with number, and just the number without bullet. (In the latter case, it seems to also add some space between that and the next item, as shown.) Presumably, I could also use the approach from your original spec.

 

Regards, Rex

 

 

From: Shane Coughlan <coughlan@...>
Sent: Wednesday, July 24, 2019 4:36 AM
To: Alexios Zavras <alexios.zavras@...>; Indira <indira.bhatt@...>; Mark Gisi <mark.gisi@...>; Rex Jaeschke <rex@...>
Cc: openchain@...; Openchain-specification@...; Alexandra Boehm <aleksa.boehm@...>
Subject: Re: [Openchain-Specification] OpenChain Specification 2.0 - Formatting for ISO - RFC

 

Hi Alexios! Indira!

 

I am looping in Rex, our ISO Editor, to take a look at your comments. One thing to bear in mind is that our ISO formatting will be keyed towards fitting into ISO conventions, which may include editorial and formatting that increases/decreases readability from our project perspective. However, our priority will be for the ISO formatted version to align with existing ISO documents, so readers of other standards will inherently feel comfortable with reviewing ours.

 

Rex, Alex will be sending along an email shortly explaining we are making a (Governing Board) Sub-Group to formally review the ISO document. That review will occur over the next few weeks. However, I have also opened the dialogue with our wider community just now, as part of our open process. If you could quickly take a look at the feedback provided and could supply some context it would be super, super great.

 

Two comments below. I have replied to one with some notes in RED. Mark (explicit CC), this might be something for you to have a look at as it includes a suggested rewording of the spec.

 

Regards

 

Shane

 

On Jul 20, 2019, at 1:46, Zavras, Alexios <alexios.zavras@...> wrote:

Very quick notes from a first glance:

  • Changing definitions to all-lower-case makes them not stand out in the text and may confuse people who read the text, since they might not look back to see what “supplied software” or “software staff” is. 
  • More importantly, I would suggest to keep the requirements as a single chapter instead of having the six sections in this chapter each a top-level clause of their own. Yes, the table of contents might not look so interesting, but think of the effect on the conformance certification process: Going by the current modified draft you will have to answer questions related to paragraphs from 4.1 to 9.2 (instead of from 4.1.1 to 4.something).
  • Getting rid of the third-level numbers and replacing them with bullets also makes it impossible to refer to specific verification artefacts. Again, this will affect the certification process and materials.

 

 

On Jul 20, 2019, at 4:22, Indira Bhatt <indira.bhatt@...> wrote:

Some notes from my end as well.  

 

3.4

open source
software subject to one or more licenses that meet the Open Source Definition published by the Open Source Initiative [2] or the Free Software Definition [1] or similar license

We are trying to say that open source =  the licenses meet the definitions/criteria described by the OSI or FSF correct? I think this could be reworded to similar criteria rather than similar license. 

Hi Indira, I also understand our intent to date - defer to Mark - is to accept licenses that are listed as meeting the Open Source Definition or Free Software Definition and allow freedom of choice to select licenses not necessarily listed by the OSD or FSD. I am not sure why “similar license” was chosen as the wording but suggest we do not change it at this juncture unless we can confirm the change would not alter meaning. Let’s see if anyone comments :)

Also agree with Alexios about keeping the requirements to a single chapter. This would read much better. 

 

Join main@lists.openchainproject.org to automatically receive all group messages.