Re: [Openchain-Specification] OpenChain Specification 2.0 - Formatting for ISO - RFC
I have made some minor comments in the document Rex distributed.
Von: openchain-bounces@... <openchain-bounces@...>
Im Auftrag von Rex Jaeschke
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.
From: Shane Coughlan <coughlan@...>
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.