OASIS mandated terminology (and DITA markup for it)

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

OASIS mandates that specifications use specific vocabulary: "must", "must not", "should", "should not", "may", and "may not". See 1.1 Terminology at http://docs.oasis-open.org/dita/v1.2/os/spec/introduction/c-terminology.html#terminology for the formal definitions of these terms.

We did not manage to implement this for DITA 1.2, and so I am beginning to revise the spec topics so that we comply with the OASIS terminology.

Here are my suggestions/directives for folks writing any new content for the spec:

Only use these terms in as specified in the terminology topic
Avoid using the verbs "must", "should", and "may" unless you are using them as specified in 1.1 Terminology. In most cases, "may" can be changed to "might" or "can". In other cases you will need to recast sentences more thoroughly. Here are some examples of content from the DITA 1.2 spec and how I have revised it for DITA 1.3 (emphasis added).

Incorrect
"To use key references, one must understand how keys are defined and bound to resources, how a map hierarchy establishes a key space, and the interaction of keys with conditional processing."

Correct
"To use key references, it is important to understand how keys are defined and bound to resources, how a map hierarchy establishes a key space, and how keys interact with conditional processing."

Incorrect
"Content may be chunked (divided or merged into new output documents) in different ways for the purposes of authoring, for delivering content, and for navigation. For example, something best authored as a set of separate topics may need to be delivered as a single Web page."

Correct
"Content can be chunked (divided or merged into new output documents) in different ways for the purposes of delivering content and navigation. For example, content best authored as a set of separate topics might need to be delivered as a single Web page."

Incorrect
"Some translation tools support changing the value of an existing @xml:lang attribute, but do not support adding new markup to the document being translated. Therefore, if the author of the source language content does not set the @xml:lang attribute, it may not be possible (or may be difficult) for the translator to add the @xml:lang attribute to the translated document."

Correct
"... Therefore, if the author of the source language content does not set the @xml:lang attribute, it might be difficult or impossible for the translator to add the @xml:lang attribute to the translated document.

Use specific DITA markup to ensure proper rendering in output formats
Use the following markup for this terminology:

• <term outputclass="OASIS-terminology">must</term
• <term outputclass="OASIS-terminology">must not</term
• <term outputclass="OASIS-terminology">should</term> 
• <term outputclass="OASIS-terminology">should not</term>
• <term outputclass="OASIS-terminology">may</term>

If you change DITA 1.2 wording to comply with the OASIS terminology, apply a @rev="terminology" attribute to the changed content. Use either <ph> or <keyword> to hold the @rev attribute.

If you use oXygen, the permissable values for the @rev and @outputclass attributes are controlled by the subjectScheme map in play for the spec.

Comment out the original wording

Example
"If used, <!--it is recommended to specify--> the dir attribute <term outputclass="OASIS-terminology" rev="terminology">should</term> be specified on the
highest level element in the topic or document element of the map."

--
Best,
Kris

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