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)


DITA and ISO is certainly something that we can consider, but getting DITA 1.3 out the door is the current priority.

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 5:33 PM, JoAnn Hackos wrote:
Hi,
Since I've been on the ISO WG7 for many years and am now actively engaged as the chief author of the new 26531 content management standard, I've learned a lot about the process. For our current standard, we are cooperating with the IEEE. Both ISO and IEEE have held first votes on this standard, with a raft of comments for us to take into account. Both organizations had high percentage votes in favor (IEEE was 95%). We have had to conform to some of both standards. We are using ISO language throughout (shall, should, may) but we had to make some changes in the draft to comply with the IEEE guidelines prior to submitting it for their vote. Generally, I have found these groups to be more picky than OASIS about language and format.

I do think getting DITA out under ISO would be a huge benefit and attract more attention, especially in Europe and Asia. 

ISO documents are unfortunately published in MSWord although rumor has it that they may change. I wrote the standard in DITA, of course, and then output to RDF. One of the WG7 editors but everything into the ugly Word format for the reviews. A real pain using Word, as you can imagine.

Anyway, I think we should look into this. I've thought so from the beginning of our DITA effort.

Best,
JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586

 

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




From: Chet Ensign <chet.ensign@oasis-open.org>
Date: Tuesday, November 5, 2013 3:25 PM
To: Don R Day <donrday@contelligencegroup.com>
Cc: Kristen James Eberlein <kris@eberleinconsulting.com>, DITA TC <dita@lists.oasis-open.org>, Jamie Clark <jamie.clark@oasis-open.org>
Subject: Re: [dita] OASIS mandated terminology (and DITA markup for it)

Hi Don, 

I copy Jamie on my reply because can speak much more thoroughly on this subject than I can. He has a lot more experience with standards submitted to the ISO than I do. 

Given that the TC will be publishing the specification from DITA, there *may* be some coordination issues with the ISO in getting it through their publishing process. Pure speculation on my part but something that might have bearing. 

The bigger issue though that occurs to me is that you are, effectively, gaining a partner here. That is, by making the submission to the ISO (or any other standards organization for that matter) you are making certain commitments and taking on certain obligations for the future. For example, you are making the commitment to keep the partner organization apprised of changes in the future and, should you have the next iteration reach OASIS Standard three years down the road, that you will submit that update to them. 

I don't believe this is necessarily onerous. It certainly does not appear to have prevented any TCs from continuing to work on their specs. If maintenance is retained by the TC - and that is how we do all our submissions - then there is no concern with the OS somehow forking or having the other org block your future developments. 

Jamie, do you have anything to add on this? 

Thx, 

/chet 



On Tue, Nov 5, 2013 at 4:44 PM, Don R Day <donrday@contelligencegroup.com> wrote:
Chet, awhile back I recall Jamie advising about possible limiting effects of choosing to go with ISO standardization that may affect our current user base down the road (impact to future OASIS-side decisions, for example). I realize that the other side of the coin is that an ISO version enables attracting possible new users. We need to be certain we make that choice with our eyes open and with full TC agreement. Can you ascertain how co-approving a standard as both OASIS and ISO affects our alternative futures? That data may help us determine whether to even go with ISO, if Patrick says that our case could do so.
--
Don


On 11/5/2013 3:17 PM, Chet Ensign wrote:
Also, one note on that - my understanding of the current ISO IEC JTC1 submission process is that for the first submission, the keywords do not need to be ISO. I think on future update, they need to change. Patrick knows that in detail.


On Tue, Nov 5, 2013 at 4:13 PM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:
JoAnn, we cannot consider that change in the DITA 1.3 time frame. The RFC2119 terminology was partially implemented for DITA 1.2.


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 4:05 PM, JoAnn Hackos wrote:
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

--------------------------------------------------------------------- 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

--
  • "Where is the wisdom we have lost in knowledge?
  • Where is the knowledge we have lost in information?"
  • --T.S. Eliot



--

/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



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