[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: OASIS mandated terminology (and DITA markup for it)
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:
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) |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]