OASIS Darwin Information Typing Architecture (DITA) TC

Some of the comments on the latest conformance topic were to the effect that
phases like "claims to be DITA aware" should be changed to something else.

My use of "claims to be" was very deliberate.

My reasoning is that one can only judge the DITA conformance of tools that
claim to be DITA aware. This is because, as an XML application, *any* XML
processor can do useful things with DITA content but only those that *claim*
to be DITA-aware processors can be held to the conformance requirements of
the DITA spec.

That is, just because a given processor happens to process DITA content does
not, by itself, impose DITA conformance requirements on that processor.

This is something I learned from being a judge at an amateur beer brewing
competition: the beer is judged on the category the brewer places it in, not
the category the judges *think* it should have been placed in. Thus, if a
brewer places what's obviously a porter in the lager category, it must be
judged by the rules for lagers, not the rules for porters.

So it is with processors handling DITA content: a processor can only be
judged on DITA conformance if the processor asserts that it is in fact a
DITA-aware processor.

That is, there is no useful sense in which a given processor is or is not
DITA conforming without first determining whether or not the processor
considers itself to be DITA aware.

If a processor does not claim DITA awareness it falls outside the purview of
the DITA spec and cannot be judged to be either DITA conforming or
non-conforming, because DITA conformance is not relevant. We may be able to
determine that such a tool *would or would not* be a conforming DITA
processor but it would be inappropriate to say that such a processor is or
is not a conforming DITA processor. It is simply not a DITA-aware processor.

In particular, it is important for DITA users to understand that they MAY
NOT describe a given XML processor as non-DITA-conforming unless that
processor explicitly claims to be DITA aware.

For example, an XML editor that does not claim to be DITA aware should not
be described as a non-conforming DITA application. It MAY be described as a
non-DITA-aware application (because it has not claimed to be DITA aware).

By the same token, if a processor claims to be DITA aware then it may be
judged on its conformance to the DITA spec.  That is, once you claim DITA
awareness, DITA conformance is a binary check, just as it is for XML or any
other similar standard. You either conform or you don't to rules for those
DITA features that are relevant to the processor.

Note that the question is not whether or not a processor claims to
*conform*, it's a question of whether or not it claim to be DITA *aware*.
Awareness requires conformance.

And just to be clear, as currently written, the conformance clause
recognizes what are effectively two levels of DITA conformance:
non-specialization-aware and specialization-aware.

Non-specialiation-aware processors need only implement those specific DITA
vocabulary modules (standard or not) that they want to support and need not
handle any others. 

Specialization-aware processors MUST process all valid DITA content,
regardless of specialization, at least in terms of their most general types.
[That is, a specialization-aware processor need not be aware of the specific
semantics of a given specialization, only of the semantics of one of its
base types.]

This implies, necessarily, that specialization-aware processors should also
be general-purpose processors, meaning that they implement all *potentially
applicable* DITA features, including conref, keyref, map processing, etc. We
have no defined mechanism for saying that a given conforming
specialization-aware processor implements conref but not keyref, for
example.

By contrast, non-specialization-aware processors, because they are
necessarily bound to specific vocabulary modules, need only implement those
features actually used by those modules.

Because a given vocabulary module can disallow markup related to specific
features (e.g., @conref, @keyref, etc.), a given vocabulary module may only
require a subset of DITA features.

Said another way: the set of relevant features for non-specialization-aware
processors is defined by the set of vocabulary modules they claim to support
while the set of relevant features for specialization-aware processors is
defined by the DITA spec relative to the *type* of processing the processor
does.

This distinction between specialization-aware and non-specialization-aware
allows one to create special-purpose DITA-aware processors that correctly
implement the features used by the vocabulary modules they do support
without requiring all conforming DITA processors to be completely
generalized.

Consider the case of business documents: it may be useful to define a highly
restricted set of vocabulary modules for business documents that disallow
both conref and keyref and define a very limited set of element types. One
could then have conforming processors that understand only these very
limited vocabulary modules. Assuming they are otherwise correctly
implemented, such processors would be DITA-aware but need not be
specialization aware and would not need to implement either conref or
keyref. 

Cheers,

Eliot   

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com

Eliot,

I was one of those who commented on "claims to be DITA aware." 

I think the thing that tripped me up was the second sentence under
"Conformance of Processors," "A processor is DITA-aware if it claims to
implement DITA-specific processing beyond that required to process XML
documents in general." Given that definition, my blender is DITA-aware
if I claim that it is. I don't see the utility in defining a term that
doesn't have some substantive meaning.

While I see your point about a claim being necessary, the way it's
stated in the conformance statement is not what I think you meant, and
in any case is more complex than it needs to be.

I suggest a different strategy to use in place of the description of
"claims to be DITA aware.". Why not make one requirement of a conforming
DITA-aware or DITA-specialization-aware processor be a statement as to
which features of DITA it supports?  Without the statement, a processor
by definition cannot be considered conforming, which I think addresses
your concern. In addition, potential users get a statement of what the
tool supports. Given how broadly non-specialization-aware processor is
defined, such a statement would be really helpful (I'd argue essential).

I hope that helps.

Dick Hamilton
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
(970) 231-3624 


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Sunday, February 21, 2010 10:28 AM
> To: dita
> Subject: [dita] Use of "claims to be DITA aware": Why I Said 
> It Like That
> 
> 
> Some of the comments on the latest conformance topic were to 
> the effect that
> phases like "claims to be DITA aware" should be changed to 
> something else.
> 
> My use of "claims to be" was very deliberate.
> 
> My reasoning is that one can only judge the DITA conformance 
> of tools that
> claim to be DITA aware. This is because, as an XML 
> application, *any* XML
> processor can do useful things with DITA content but only 
> those that *claim*
> to be DITA-aware processors can be held to the conformance 
> requirements of
> the DITA spec.
> 
> That is, just because a given processor happens to process 
> DITA content does
> not, by itself, impose DITA conformance requirements on that 
> processor.
> 
> This is something I learned from being a judge at an amateur 
> beer brewing
> competition: the beer is judged on the category the brewer 
> places it in, not
> the category the judges *think* it should have been placed 
> in. Thus, if a
> brewer places what's obviously a porter in the lager 
> category, it must be
> judged by the rules for lagers, not the rules for porters.
> 
> So it is with processors handling DITA content: a processor 
> can only be
> judged on DITA conformance if the processor asserts that it 
> is in fact a
> DITA-aware processor.
> 
> That is, there is no useful sense in which a given processor 
> is or is not
> DITA conforming without first determining whether or not the processor
> considers itself to be DITA aware.
> 
> If a processor does not claim DITA awareness it falls outside 
> the purview of
> the DITA spec and cannot be judged to be either DITA conforming or
> non-conforming, because DITA conformance is not relevant. We 
> may be able to
> determine that such a tool *would or would not* be a conforming DITA
> processor but it would be inappropriate to say that such a 
> processor is or
> is not a conforming DITA processor. It is simply not a 
> DITA-aware processor.
> 
> In particular, it is important for DITA users to understand 
> that they MAY
> NOT describe a given XML processor as non-DITA-conforming unless that
> processor explicitly claims to be DITA aware.
> 
> For example, an XML editor that does not claim to be DITA 
> aware should not
> be described as a non-conforming DITA application. It MAY be 
> described as a
> non-DITA-aware application (because it has not claimed to be 
> DITA aware).
> 
> By the same token, if a processor claims to be DITA aware 
> then it may be
> judged on its conformance to the DITA spec.  That is, once 
> you claim DITA
> awareness, DITA conformance is a binary check, just as it is 
> for XML or any
> other similar standard. You either conform or you don't to 
> rules for those
> DITA features that are relevant to the processor.
> 
> Note that the question is not whether or not a processor claims to
> *conform*, it's a question of whether or not it claim to be 
> DITA *aware*.
> Awareness requires conformance.
> 
> And just to be clear, as currently written, the conformance clause
> recognizes what are effectively two levels of DITA conformance:
> non-specialization-aware and specialization-aware.
> 
> Non-specialiation-aware processors need only implement those 
> specific DITA
> vocabulary modules (standard or not) that they want to 
> support and need not
> handle any others. 
> 
> Specialization-aware processors MUST process all valid DITA content,
> regardless of specialization, at least in terms of their most 
> general types.
> [That is, a specialization-aware processor need not be aware 
> of the specific
> semantics of a given specialization, only of the semantics of 
> one of its
> base types.]
> 
> This implies, necessarily, that specialization-aware 
> processors should also
> be general-purpose processors, meaning that they implement 
> all *potentially
> applicable* DITA features, including conref, keyref, map 
> processing, etc. We
> have no defined mechanism for saying that a given conforming
> specialization-aware processor implements conref but not keyref, for
> example.
> 
> By contrast, non-specialization-aware processors, because they are
> necessarily bound to specific vocabulary modules, need only 
> implement those
> features actually used by those modules.
> 
> Because a given vocabulary module can disallow markup related 
> to specific
> features (e.g., @conref, @keyref, etc.), a given vocabulary 
> module may only
> require a subset of DITA features.
> 
> Said another way: the set of relevant features for 
> non-specialization-aware
> processors is defined by the set of vocabulary modules they 
> claim to support
> while the set of relevant features for specialization-aware 
> processors is
> defined by the DITA spec relative to the *type* of processing 
> the processor
> does.
> 
> This distinction between specialization-aware and 
> non-specialization-aware
> allows one to create special-purpose DITA-aware processors 
> that correctly
> implement the features used by the vocabulary modules they do support
> without requiring all conforming DITA processors to be completely
> generalized.
> 
> Consider the case of business documents: it may be useful to 
> define a highly
> restricted set of vocabulary modules for business documents 
> that disallow
> both conref and keyref and define a very limited set of 
> element types. One
> could then have conforming processors that understand only these very
> limited vocabulary modules. Assuming they are otherwise correctly
> implemented, such processors would be DITA-aware but need not be
> specialization aware and would not need to implement either conref or
> keyref. 
> 
> Cheers,
> 
> Eliot   
> 
> -- 
> Eliot Kimber
> Senior Solutions Architect
> "Bringing Strategy, Content, and Technology Together"
> Main: 610.631.6770
> www.reallysi.com
> www.rsuitecms.com
> 
> 
> ---------------------------------------------------------------------
> 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_workgr
> oups.php 
> 
> 

On 2/21/10 7:03 PM, "Dick Hamilton" 

I too had qualms about the word "claim" but I may not have voiced them.
It is legitimate semantics for the marketing of tools, so it is relevant
to the TC's role adjudicating conformance to the spec.

Here's my attempt to summarize this discussion for myself. Maybe it can
be useful.

Within the spec, the terms "DITA aware" and "specialization aware" are
redundant. The relevant distinction is whether a tool is conforming or
not. As you say, Eliot, if a tool makes no claim to support DITA, the
question of conformity does not arise. We don't even have to be
concerned that it makes no claim. Any claim that a vendor does make is
only meaningful as a claim to be DITA conforming.

We may further identify a subset of features which are supported in a
conforming way (where the entire spec is the limiting case). And there's
the rub. "DITA aware" and "specialization aware" are marketing terms
that fog the question of how fully a tool conforms to the spec. They are
useful only to a vendor that wants to claim that their tool supports
DITA even though they cannot demonstrate full conformity. 

Perhaps the remedy is to establish the legitimacy of partial
conformity--e.g. we don't support feature x but that doesn't matter
because our customers don't use or care about feature x.

> We have already established that it is not realistically 
> possible in the 1.2 time frame to define an enumerated set of 
> features in order to then label them as required, optional, etc.

A few months ago, I asked JoAnn and others if there was a list of 1.2
features. I had gone through threads on the dita alias and gleaned a
list. The Adoption TC is using that list now. Maybe it would be feasible
even within our time constraints to confirm its completeness?

My thinking: A list of features is useful to vendors because it helps to
level the marketing field, but it is not essential for the TC when it is
called upon to judge partial conformance. Further, since the DITA TC is
the adjudicating body, and because the standard of judgement is the spec
and not any feature list derived from the spec, we are empowered to
refine the feature list over time based on experience with the
adjudication process. 

This presumes that we do have a process in place that brings vendors
before us for judgement of their marketing claims (there's that word). 

	/Bruce

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Sunday, February 21, 2010 10:55 PM
> To: Dick Hamilton; dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> On 2/21/10 7:03 PM, "Dick Hamilton" 

Bruce and Eliot,

A couple of points/questions:

From Bruce:
>
> My thinking: A list of features is useful to vendors because 
> it helps to level the marketing field, but it is not essential
> for the TC when it is called upon to judge partial conformance.
>
> 

On 2/22/10 1:21 PM, "Dick Hamilton" 

Eliot,

> > What do you mean by "judging" marketing claims?
> > I may have missed this being a relative newcomer,
> > but I didn't think the TC was planning to
> > take an active role in judging conformance.
> 
> The TC makes the law, it doesn't enforce it.
> 
Glad to hear that. I thought it was unlikely, but since there was at
least the implication in some of the messages in this thread, I thought
the point should be explicitly addressed.

Thanks again for the clarification.

Dick
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
(970) 231-3624 


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Monday, February 22, 2010 12:39 PM
> To: Dick Hamilton; Bruce Nevin (bnevin); dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> 
> On 2/22/10 1:21 PM, "Dick Hamilton" 

Tony Self made a good comment on the Adoption TC list today:

"From my reading of the conformance topic in the spec itself, it seems a
vendor can claim DITA conformance by writing their own conformance
statement. There's no template for such a statement. One requirement of
such a statement is that it lists the DITA features that the tool
supports, but I couldn't find a definitive list of DITA features. If
that's the case, then one vendor might claim "re-use" as a supported
DITA feature, while another might claim "topicref" as a supported DITA
feature. How does a bewildered new DITA adopter compare these tools?

...

Examples of the problem can easily be found. There is a technical
authoring tool that uses a proprietary data storage format that claims
to "publish" to XML outputs including "OASIS compliant DITA". It turns
out that out-of-the-box you can probably publish some topics to "topic"
information types with lots of "required-cleanup" blocks. Technically,
that's "OASIS compliant DITA", but practically, it's meaningless. The
way I look at it, that tool is not a DITA processor at all. (By the way,
some confused participants in the WritePoint DITA Challenges Survey
listed that tool as a DITA tool, and identified themselves as DITA
adopters.) If vendors can devise their own compliance statements, those
statements will end up reading like marketing blurbs, and obfuscate the
information most important to the end user."

I think it would be difficult for any committee to agree upon a template
that fairly differentiates the four or five *major* DITA authoring tools
from each other. Worth trying perhaps, but difficult. However,
distinguishing DITA authoring tools from the kind of application that
Tony refers to in the second paragraph above should be considerably
easier, and I suggest that the DITA 1.2 conformance statement try to do
this with something along the lines of the following:

"Tools that claim to support DITA authoring must allow authors to create
and edit arbitrary valid documents using the complete base DITA
vocabulary, i.e. all DITA topic and map types, including all base
element and attribute types. They must also must also document
procedures to support creating and editing arbitrary valid documents
using arbitrary DITA specializations. Tools that claim to partially
support DITA authoring and do not support creation and editing of
arbitrary valid documents using the complete base DITA vocabulary must
document what parts of the vocabulary are not supported. "

This statement would, I hope, mean that tool vendors which only "output
as DITA" have to stop claiming that they support DITA authoring. They
can claim to partially support DITA authoring, with an asterisk and a
long footnote. 

As discussed earlier in the thread, OASIS can't stop people from
claiming anything, but we can empower those who promote critical
thinking.

Cheers,
Su-Laine


Su-Laine Yeo
Solutions Consultant 
JustSystems Canada, Inc.
Office: 778-327-6356 
syeo@justsystems.com
www.justsystems.com 
XMetaL Community Forums: http://forums.xmetal.com/




-----Original Message-----
From: Dick Hamilton [mailto:rlhamilton@frii.com] 
Sent: Monday, February 22, 2010 1:01 PM
To: 'Eliot Kimber'; 'Bruce Nevin (bnevin)'; 'dita'
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Eliot,

> > What do you mean by "judging" marketing claims?
> > I may have missed this being a relative newcomer,
> > but I didn't think the TC was planning to
> > take an active role in judging conformance.
> 
> The TC makes the law, it doesn't enforce it.
> 
Glad to hear that. I thought it was unlikely, but since there was at
least the implication in some of the messages in this thread, I thought
the point should be explicitly addressed.

Thanks again for the clarification.

Dick
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
(970) 231-3624 


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Monday, February 22, 2010 12:39 PM
> To: Dick Hamilton; Bruce Nevin (bnevin); dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> 
> On 2/22/10 1:21 PM, "Dick Hamilton" 

Here's a revised proposal with tweaks to more directly address "output
as DITA" claims:

"Tools that claim to support DITA authoring, or claim to support
producing output as DITA, must allow authors to create arbitrary valid
documents using the complete base DITA vocabulary, i.e. all DITA topic
and map types, including all base element and attribute types. They must
also must also document procedures to support creating arbitrary valid
documents using arbitrary DITA specializations. Tools that claim partial
support of DITA authoring or partial support of producing output as
DITA, but do not support creation of arbitrary valid documents using the
complete base DITA vocabulary, must document what parts of the
vocabulary are not supported."


Su-Laine


-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
Sent: Monday, February 22, 2010 3:43 PM
To: dita; tony.self@hyperwrite.com
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Tony Self made a good comment on the Adoption TC list today:

"From my reading of the conformance topic in the spec itself, it seems a
vendor can claim DITA conformance by writing their own conformance
statement. There's no template for such a statement. One requirement of
such a statement is that it lists the DITA features that the tool
supports, but I couldn't find a definitive list of DITA features. If
that's the case, then one vendor might claim "re-use" as a supported
DITA feature, while another might claim "topicref" as a supported DITA
feature. How does a bewildered new DITA adopter compare these tools?

...

Examples of the problem can easily be found. There is a technical
authoring tool that uses a proprietary data storage format that claims
to "publish" to XML outputs including "OASIS compliant DITA". It turns
out that out-of-the-box you can probably publish some topics to "topic"
information types with lots of "required-cleanup" blocks. Technically,
that's "OASIS compliant DITA", but practically, it's meaningless. The
way I look at it, that tool is not a DITA processor at all. (By the way,
some confused participants in the WritePoint DITA Challenges Survey
listed that tool as a DITA tool, and identified themselves as DITA
adopters.) If vendors can devise their own compliance statements, those
statements will end up reading like marketing blurbs, and obfuscate the
information most important to the end user."

I think it would be difficult for any committee to agree upon a template
that fairly differentiates the four or five *major* DITA authoring tools
from each other. Worth trying perhaps, but difficult. However,
distinguishing DITA authoring tools from the kind of application that
Tony refers to in the second paragraph above should be considerably
easier, and I suggest that the DITA 1.2 conformance statement try to do
this with something along the lines of the following:

"Tools that claim to support DITA authoring must allow authors to create
and edit arbitrary valid documents using the complete base DITA
vocabulary, i.e. all DITA topic and map types, including all base
element and attribute types. They must also must also document
procedures to support creating and editing arbitrary valid documents
using arbitrary DITA specializations. Tools that claim to partially
support DITA authoring and do not support creation and editing of
arbitrary valid documents using the complete base DITA vocabulary must
document what parts of the vocabulary are not supported. "

This statement would, I hope, mean that tool vendors which only "output
as DITA" have to stop claiming that they support DITA authoring. They
can claim to partially support DITA authoring, with an asterisk and a
long footnote. 

As discussed earlier in the thread, OASIS can't stop people from
claiming anything, but we can empower those who promote critical
thinking.

Cheers,
Su-Laine


Su-Laine Yeo
Solutions Consultant 
JustSystems Canada, Inc.
Office: 778-327-6356 
syeo@justsystems.com
www.justsystems.com 
XMetaL Community Forums: http://forums.xmetal.com/




-----Original Message-----
From: Dick Hamilton [mailto:rlhamilton@frii.com] 
Sent: Monday, February 22, 2010 1:01 PM
To: 'Eliot Kimber'; 'Bruce Nevin (bnevin)'; 'dita'
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Eliot,

> > What do you mean by "judging" marketing claims?
> > I may have missed this being a relative newcomer,
> > but I didn't think the TC was planning to
> > take an active role in judging conformance.
> 
> The TC makes the law, it doesn't enforce it.
> 
Glad to hear that. I thought it was unlikely, but since there was at
least the implication in some of the messages in this thread, I thought
the point should be explicitly addressed.

Thanks again for the clarification.

Dick
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
(970) 231-3624 


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Monday, February 22, 2010 12:39 PM
> To: Dick Hamilton; Bruce Nevin (bnevin); dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> 
> On 2/22/10 1:21 PM, "Dick Hamilton" 

Hi Su-Laine (and all)

Your revised text doesn't allow for the differentiation between DITA-aware
and specialisation-aware. Maybe the text could be separated into two pieces,
starting with (respectively):

"Tools that claim to support base content model DITA authoring..."
and
"Tools that claim to support specialised content model DITA authoring..."

Would the requirement that the tool provide access to all elements and
attributes be too restrictive for both "abstraction layer" authoring tools
and very specialised authoring tools (such as an authoring tool designed for
creating reference topics only)? I think it *would* be too restrictive, but
I can't immediately think of another way of expressing the conformance
requirement.

Tony Self



-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
Sent: Tuesday, 23 February 2010 11:17 AM
To: dita; tony.self@hyperwrite.com
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Here's a revised proposal with tweaks to more directly address "output
as DITA" claims:

"Tools that claim to support DITA authoring, or claim to support
producing output as DITA, must allow authors to create arbitrary valid
documents using the complete base DITA vocabulary, i.e. all DITA topic
and map types, including all base element and attribute types. They must
also must also document procedures to support creating arbitrary valid
documents using arbitrary DITA specializations. Tools that claim partial
support of DITA authoring or partial support of producing output as
DITA, but do not support creation of arbitrary valid documents using the
complete base DITA vocabulary, must document what parts of the
vocabulary are not supported."


Su-Laine

Hi Tony,

Regarding differentiation between DITA-aware and specialization-aware, I
was hoping to cover that in the second sentence which says, "They must
also must also document procedures to support creating arbitrary valid
documents using arbitrary DITA specializations." Maybe this could be
clarified by saying instead, "Tools that claim to support specialization
must also document procedures for creating arbitrary valid documents
using arbitrary DITA specializations." BTW this procedure could be
"contact us for a quote."

> Would the requirement that the tool provide access to all elements and
> attributes be too restrictive for both "abstraction layer" authoring
tools
> and very specialised authoring tools (such as an authoring tool
designed for
> creating reference topics only)? 

These tools could still claim to partially support DITA authoring, which
is what they aspire to do. 
I must say though that I'm not confident that a conformance statement
can outsmart vendor marketing spin.   

Su-Laine

-----Original Message-----
From: Tony Self [mailto:tself@hyperwrite.com] 
Sent: Monday, February 22, 2010 5:07 PM
To: Su-Laine Yeo; 'dita'
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Hi Su-Laine (and all)

Your revised text doesn't allow for the differentiation between
DITA-aware
and specialisation-aware. Maybe the text could be separated into two
pieces,
starting with (respectively):

"Tools that claim to support base content model DITA authoring..."
and
"Tools that claim to support specialised content model DITA
authoring..."

Would the requirement that the tool provide access to all elements and
attributes be too restrictive for both "abstraction layer" authoring
tools
and very specialised authoring tools (such as an authoring tool designed
for
creating reference topics only)? I think it *would* be too restrictive,
but
I can't immediately think of another way of expressing the conformance
requirement.

Tony Self



-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
Sent: Tuesday, 23 February 2010 11:17 AM
To: dita; tony.self@hyperwrite.com
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Here's a revised proposal with tweaks to more directly address "output
as DITA" claims:

"Tools that claim to support DITA authoring, or claim to support
producing output as DITA, must allow authors to create arbitrary valid
documents using the complete base DITA vocabulary, i.e. all DITA topic
and map types, including all base element and attribute types. They must
also must also document procedures to support creating arbitrary valid
documents using arbitrary DITA specializations. Tools that claim partial
support of DITA authoring or partial support of producing output as
DITA, but do not support creation of arbitrary valid documents using the
complete base DITA vocabulary, must document what parts of the
vocabulary are not supported."


Su-Laine

This entire discussion hopeless. It is the reason that the TC previously
agreed that we could not and would not produce the sort of detailed
conformance statement for DITA 1.2 that we had once hoped.  We should
just stop trying.  If we continue to try to go down this road, we will
never finish.

And just to be clear, all of the revised wording that has been suggested
by various people seems unacceptable to me.

I do think that Eliot understands what needs to be done and has written
some quite clear statements about it.  And I want to thank him for that.

I do think that asking vendors that claim DITA awareness to list the
DITA features they do and/or don't support would be a good thing.  We
had that in the conformance statement at one point.  Why did we take it
out?

Such a list would be a step in the right direction, but it won't be
perfect until the DITA spec. has its own list of required and optional
features for different categories of implementation.  That isn't going
to happen in the short run.  But a vendor supplied list of supported and
unsupported features would still be a step in the right direction. 

    -Jeff

> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> Sent: Monday, February 22, 2010 9:03 PM
> To: tself@hyperwrite.com; dita
> Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It
> Like That
> 
> Hi Tony,
> 
> Regarding differentiation between DITA-aware and specialization-aware,
> I
> was hoping to cover that in the second sentence which says, "They must
> also must also document procedures to support creating arbitrary valid
> documents using arbitrary DITA specializations." Maybe this could be
> clarified by saying instead, "Tools that claim to support
> specialization
> must also document procedures for creating arbitrary valid documents
> using arbitrary DITA specializations." BTW this procedure could be
> "contact us for a quote."
> 
> > Would the requirement that the tool provide access to all elements
> and
> > attributes be too restrictive for both "abstraction layer" authoring
> tools
> > and very specialised authoring tools (such as an authoring tool
> designed for
> > creating reference topics only)?
> 
> These tools could still claim to partially support DITA authoring,
> which
> is what they aspire to do.
> I must say though that I'm not confident that a conformance statement
> can outsmart vendor marketing spin.
> 
> Su-Laine
> 
> -----Original Message-----
> From: Tony Self [mailto:tself@hyperwrite.com]
> Sent: Monday, February 22, 2010 5:07 PM
> To: Su-Laine Yeo; 'dita'
> Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It
> Like
> That
> 
> Hi Su-Laine (and all)
> 
> Your revised text doesn't allow for the differentiation between
> DITA-aware
> and specialisation-aware. Maybe the text could be separated into two
> pieces,
> starting with (respectively):
> 
> "Tools that claim to support base content model DITA authoring..."
> and
> "Tools that claim to support specialised content model DITA
> authoring..."
> 
> Would the requirement that the tool provide access to all elements and
> attributes be too restrictive for both "abstraction layer" authoring
> tools
> and very specialised authoring tools (such as an authoring tool
> designed
> for
> creating reference topics only)? I think it *would* be too
restrictive,
> but
> I can't immediately think of another way of expressing the conformance
> requirement.
> 
> Tony Self
> 
> 
> 
> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> Sent: Tuesday, 23 February 2010 11:17 AM
> To: dita; tony.self@hyperwrite.com
> Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It
> Like
> That
> 
> Here's a revised proposal with tweaks to more directly address "output
> as DITA" claims:
> 
> "Tools that claim to support DITA authoring, or claim to support
> producing output as DITA, must allow authors to create arbitrary valid
> documents using the complete base DITA vocabulary, i.e. all DITA topic
> and map types, including all base element and attribute types. They
> must
> also must also document procedures to support creating arbitrary valid
> documents using arbitrary DITA specializations. Tools that claim
> partial
> support of DITA authoring or partial support of producing output as
> DITA, but do not support creation of arbitrary valid documents using
> the
> complete base DITA vocabulary, must document what parts of the
> vocabulary are not supported."
> 
> 
> Su-Laine
> 
> 
> ---------------------------------------------------------------------
> 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

Hi Tony and Su-Laine,

As a employee of a vendor whose solution supports the definition you have provided below, but whose focus is on a market where the understanding of "DITA aware and specialization aware" represents a set of requirements that is closer to Tony's text, I would gently suggest that this subject is very complicated and it will take considerable work to come up with a statement that provides the value you are looking for. I think the effort is worth it, and would like to contribute where it would be helpful.

The statement in its final form below might not be seen as presenting a view of implementation that is designed to encourage approaches that meet the broadest spectrum of market requirements. I do agree that it supports the most rigid definition of a technically oriented XML editor, but I hope we all want to see the DITA user community expand well beyond the potential users of this technical type of tool. Of course the technical tools can generally be made accessible to a variety of users, but then we are back to the "contact us for a quote" mode. 

The truth is that tools are created with a specific user profile in mind, and I think we will do a disservice to DITA if we arbitrarily close the "what supports DITA" gate too tightly. On the other hand, we will do a service to both end users and DITA if we create language that helps identify the vendors who claim to support DITA simply because it has gained so much attention without any substance behind the claim.  

Very glad to see this discussion because there is a need for this.

Michael

Michael Boses
Director, XML Products
Quark Inc.

Co-Chair OASIS DITA for Enterprise Business Documents Subcommittee
http://wiki.oasis-open.org/dita/BusDocs



      



-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
Sent: Monday, February 22, 2010 9:03 PM
To: tself@hyperwrite.com; dita
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like That

Hi Tony,

Regarding differentiation between DITA-aware and specialization-aware, I
was hoping to cover that in the second sentence which says, "They must
also must also document procedures to support creating arbitrary valid
documents using arbitrary DITA specializations." Maybe this could be
clarified by saying instead, "Tools that claim to support specialization
must also document procedures for creating arbitrary valid documents
using arbitrary DITA specializations." BTW this procedure could be
"contact us for a quote."

> Would the requirement that the tool provide access to all elements and
> attributes be too restrictive for both "abstraction layer" authoring
tools
> and very specialised authoring tools (such as an authoring tool
designed for
> creating reference topics only)? 

These tools could still claim to partially support DITA authoring, which
is what they aspire to do. 
I must say though that I'm not confident that a conformance statement
can outsmart vendor marketing spin.   

Su-Laine

-----Original Message-----
From: Tony Self [mailto:tself@hyperwrite.com] 
Sent: Monday, February 22, 2010 5:07 PM
To: Su-Laine Yeo; 'dita'
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Hi Su-Laine (and all)

Your revised text doesn't allow for the differentiation between
DITA-aware
and specialisation-aware. Maybe the text could be separated into two
pieces,
starting with (respectively):

"Tools that claim to support base content model DITA authoring..."
and
"Tools that claim to support specialised content model DITA
authoring..."

Would the requirement that the tool provide access to all elements and
attributes be too restrictive for both "abstraction layer" authoring
tools
and very specialised authoring tools (such as an authoring tool designed
for
creating reference topics only)? I think it *would* be too restrictive,
but
I can't immediately think of another way of expressing the conformance
requirement.

Tony Self



-----Original Message-----
From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
Sent: Tuesday, 23 February 2010 11:17 AM
To: dita; tony.self@hyperwrite.com
Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It Like
That

Here's a revised proposal with tweaks to more directly address "output
as DITA" claims:

"Tools that claim to support DITA authoring, or claim to support
producing output as DITA, must allow authors to create arbitrary valid
documents using the complete base DITA vocabulary, i.e. all DITA topic
and map types, including all base element and attribute types. They must
also must also document procedures to support creating arbitrary valid
documents using arbitrary DITA specializations. Tools that claim partial
support of DITA authoring or partial support of producing output as
DITA, but do not support creation of arbitrary valid documents using the
complete base DITA vocabulary, must document what parts of the
vocabulary are not supported."


Su-Laine


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

> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> Sent: Monday, February 22, 2010 10:17 PM
> To: dita; tony.self@hyperwrite.com
> Subject: RE: [dita] Use of "claims to be DITA aware": Why I Said It
> Like That
> 
> Here's a revised proposal with tweaks to more directly address "output
> as DITA" claims:
> 
> "Tools that claim to support DITA authoring, or claim to support
> producing output as DITA, must allow authors to create arbitrary valid
> documents using the complete base DITA vocabulary, i.e. all DITA topic
> and map types, including all base element and attribute types. They
> must
> also must also document procedures to support creating arbitrary valid
> documents using arbitrary DITA specializations. Tools that claim
> partial
> support of DITA authoring or partial support of producing output as
> DITA, but do not support creation of arbitrary valid documents using
> the
> complete base DITA vocabulary, must document what parts of the
> vocabulary are not supported."


Hi Su-Laine,

There are different kinds of DITA processors that go beyond authoring and publishing. Translation tools, for example, also need to be aware of DITA particularities. 

It would be very difficult to write a conformance clause that covers all. Perhaps a simple and permissive one would be better.

Regards,
Rodolfo
--
Rodolfo M. Raya   

On 2/22/10 11:46 AM, "Bruce Nevin (bnevin)" 

I do not mean they are redundant with each other. I mean that each term
is redundant, supernumary, unneeded, making no useful semantic
contribution (except for marketing purposes by vendors as noted).

The question is not so much about determining what a given tool
supports. It is about making vendors' marketing claims answerable. 

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Monday, February 22, 2010 2:27 PM
> To: Bruce Nevin (bnevin); Dick Hamilton; dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> On 2/22/10 11:46 AM, "Bruce Nevin (bnevin)" 

For the record, the conclusions taken on today's TC call have well
answered my concern about vague and ill-defined terms. It doesn't matter
whether vendors call it awareness, osmosis, or grokking, so long as
their customers can refer to conformance claims that they can verify.
Helping them with the means to verify is a task (primarily) for the
Adoption TC.

	/Bruce 

> -----Original Message-----
> From: Bruce Nevin (bnevin) 
> Sent: Monday, February 22, 2010 2:54 PM
> To: Eliot Kimber; Dick Hamilton; dita
> Subject: RE: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> I do not mean they are redundant with each other. I mean that 
> each term is redundant, supernumary, unneeded, making no 
> useful semantic contribution (except for marketing purposes 
> by vendors as noted). 
> 
> The question is not so much about determining what a given 
> tool supports. It is about making vendors' marketing claims 
> answerable. 
> 
> > -----Original Message-----
> > From: Eliot Kimber [mailto:ekimber@reallysi.com]
> > Sent: Monday, February 22, 2010 2:27 PM
> > To: Bruce Nevin (bnevin); Dick Hamilton; dita
> > Subject: Re: [dita] Use of "claims to be DITA aware": Why I Said It 
> > Like That
> > 
> > On 2/22/10 11:46 AM, "Bruce Nevin (bnevin)" 
> 

On 2/23/10 11:13 AM, "Bruce Nevin (bnevin)" 

As the person who lit the fuse (or at least fanned the flames), I
apologize for not making the meeting this morning; I've been fighting a
cold and slept right through the meeting.

I'm glad you had a productive meeting and are on track to get a good
conformance statement.

Best,
Dick Hamilton
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
(970) 231-3624 


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Tuesday, February 23, 2010 10:15 AM
> To: Bruce Nevin (bnevin); dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
> 
> On 2/23/10 11:13 AM, "Bruce Nevin (bnevin)" 

Eliot,

Your description of DITA-aware, specialization-aware, and fully
DITA-aware below is clear and makes sense to me. I think you could use
it nearly verbatim as the processor portion of the conformance
statement.

Thanks for the clarification.

Dick
---------------------------------
XML Press
XML for Technical Communicators
http://xmlpress.net
(970) 231-3624 


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Monday, February 22, 2010 12:27 PM
> To: Bruce Nevin (bnevin); Dick Hamilton; dita
> Subject: Re: [dita] Use of "claims to be DITA aware": Why I 
> Said It Like That
> 
>