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: Re: [dita] OASIS mandated terminology (and DITA markup for it)


Thanks Kris and Chet,
If we ever want the DITA spec to become an ISO standard, which I believe is a very good idea, we should follow ISO terminology for 1.3. I sent the ISO terms earlier to Kris.
JoAnn

Sent from my iPad
JoAnn Hackos
Comtech Services Inc
710 Kipling Street Suite 400
Lakewood CO 80215

Comtech Logo 2005 small

 

CIDM will be hosting the Content Management Strategies/DITA Europe Conference 2013 in Munich, Germany November 18-19. More information at:

http://www.infomanagementcenter.com/DITAeurope/2013/index.htm


On Nov 5, 2013, at 12:24 PM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote:

Thanks, Chet. I found the following especially helpful:

"[RFC 2119] keywords are written in UPPERCASE. When [RFC2119] keywords are written in lowercase, they have only their normal English usage meaning. In lowercase, [RFC2119] keywords do not state normative or conformance requirements."

I had a half-written e-mail to you asking whether we could modify our terminology topic to explain just this distinction.

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)

On 11/5/2013 1:53 PM, Chet Ensign wrote:
Hi Kristen, hello DITA TC members, 

I have attached a draft of the Keywords Guidelines document recently prepared by the TAB. We were just getting ready to circulate this to the chairs list to gather feedback before publishing it. 

The document provides guidance on using the RFC2119 keywords and, alternatively, ISO keywords. To be clear, OASIS doesn't mandate the keywords you use. We provide the RFC2119 language in templates as a default set. Some TCs may choose to use ISO keywords instead. We just strongly recommend that you pick one and then use it consistently throughout your work product. 

This document is intended to help you do that. 

As the first TC to receive it, we would certainly appreciate any feedback you have. Patrick Durusau was the author of the document and I'm sure he'll also be happy to provide feedback on it. 

Best, 

/chet 



On Tue, Nov 5, 2013 at 12:54 PM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:
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)
--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php



--

/chet 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html 

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php


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