OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RFC-2119 terminology

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:


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.

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]