RFC-2119 terminology

[Kristen James Eberlein <kris@eberleinconsulting.com>]

I want to remind folks that one of our focuses for DITA 1.3 is correctly using RFC-2119 terminology. Post-DITA 1.2, OASIS issued clearer directives about this sort of normative terminology:

https://www.oasis-open.org/policies-guidelines/keyword-guidelines

In particular, see https://www.oasis-open.org/policies-guidelines/keyword-guidelines#tc-spec-keywords . It contains the following admonition (emphasis added):

"Keywords identify the requirements for conforming to a specification or standard. RFC 2119 gives the following guidance on keywords (called "imperatives")

Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmisssions) For example, they must not be used to try to impose a particular method on implementers where the method is not required for interoperability. [RFC2119]

.<one paragraph snipped>

Normative contents don't always use keywords. Often a descriptive or declarative style reads better than an imperative style based on keywords. In that case, such content may still be referred to by a more general statement — e.g. in a conformance clause — where normative keywords are used to clearly indicate what is expected from a conforming implementation."

We need to make sure that we are following these guidelines correctly for DITA 1.3.

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)