search

tdwg / vocab

Vocabulary Maintenance Specification Task Group + SDS + VMS
11 stars 6 forks source link

Under what circumstances (if any) should the terms defined in RFC 2119 be used in TDWG Standards documentation? #19

Closed baskaufs closed 8 years ago

baskaufs commented 9 years ago

RFC 2119 defines words (usually represented in all-caps) such as "MUST" and "SHOULD NOT" for use in IETF Standards Track documents. In the context of IETF, stipulating requirements using these terms indicates that a specified technology may succeed or fail depending on whether a user conforms to the requirements specified using the vocabulary of RFC 2119. In the context of TDWG, a standard may describe a best practice rather than a technology. In this situation, failure of a user of the standard to conform to requirements specified using the vocabulary RFC 2119 may be undesirable, but probably won't result in a technological failure. So in what categories or kinds of TDWG standards is it appropriate to use the terms of RFC 2119? For an example where "must" is used in a way that doesn't mean "MUST" see Section 3 of the IETF RFC Style Guide.

ramorrismorris commented 9 years ago

FWIW, http://w3c.github.io/dwbp/bp.html has only one use conforming to RFC119 upper case usage. Finding some other W3 Best Practices docs might inform us further. Even better would be to find the W3 Best Practices for Best Practices Documents, is such exists....

Best Practice Recipes for Publishing RDF Vocabularies: 13 "must", no "MUST" Mobile Web Best Practices 1.0: 9 "must", no "MUST"

baskaufs commented 9 years ago

This was discussed at the 2015-07-15 TG meeting. There was agreement that there are circumstances under which use of terms as defined by RFC 2119 would be appropriate. We need to draft language indicating the appropriate circumstances and whether it should be required or recommended. However, no one was assigned to this task.

baskaufs commented 8 years ago

OK, I have taken a stab at adding a section (3.2.5) to the Standards Documentation Specification https://github.com/tdwg/vocab/blob/master/documentation-specification.md explaining a policy on RFC 2119. I then edited the Documentation Spec with that policy in mind. I'm not sure that it's right, so suggestions would be welcome. I'm not sure yet whether it's appropriate to apply RFC 2119 to the Vocabulary Maintenance Specification, plus I still have some significant editing to do on it. However, I think Section 3.2.5 is adequate enough for me to close this issue.