Review normative language and presentation

[olivierthereaux]

Congrats putting together the first draft specification for the syntax. It is a clear and useful document, especially so for a first iteration.

If feedback from the industry on shape and scope of the draft is positive, I would suggest iterating on the document following guidance from a few resources created to ensure that the specification should be as easy as possible to implement consistently, therefore maximising the impact of the specification on interoperability.

The W3C Specifications guidelines may be a good starting point. It is a fairly comprehensive document with many recommendations, but the first I would suggest to focus first on the language and presentation of compliance:

1. review the introduction and flow of the document to make more explicit what types of things we expect to comply to this standard, and what compliance means to them. This will allow the specification to hold useful information both for producers of data (what is expected of the syntax) but also consumers of the syntax (e.g. how to deal with non-compliance)
2. Adopt compliance-focus language, e.g. from RFC 2119. I think the draft already includes some instances of the word shall, should, may and must: we should look at whether they are colloquial uses of the words, or whether they signal levels of compliance.
3. Distinguish (through prose or presentation) sections of the specification which are normative (substantial to compliance), and which are purely informational.

[pisuke]

@olivierthereaux with the release 1.0.0 update and latest changes, do you feel we have addressed this?

[olivierthereaux]

I think this is largely addressed in 1.0.0, yes, thank you @pisuke.

I would suggest that the instances of the "shall/shall not" key words that are normative be capitalised - so as to clearly identify them as RFC2119 verbs and not more general figures of speech. A reference to the RFC in the intro may also be valuable.