Re: [dita] When does DITA Document Type Not Meet Requirements?

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

Michael Priestley wrote:

> Okay, taking this back to the list - apologies for it going off-line to 
> begin with (slip of the reply click).
> 
> In the context of suggesting how to create a new kind of list that allowed 
> groups of items, I wrote:
> 
>>>You can always specialize off of fig and ph, like I said. It's what we 
> 
> did 
> 
>>>with syntaxdiagram. Maybe it's not semantically pure, but it works.
> 
> 
> And Eliot replied:
> 
>>But semantics is everything. Specializing fig to create a new kind of 
>>list would just be wrong--it would confuse anyone who came to it and 
>>could quite possibly create unexpected results if the data was processed 
>>in terms of the base types.
> 
> 
> Whereas creating an entirely new base class for the existing DITA tag set 
> won't be confusing? If you're seriously concerned about fig being the 
> base, use nested <ph> - that's the generic building block for just about 
> anything.

I think we're talking about two different things.

I don't recognize "creating a new base class for the existing DITA tag 
set" as a meaningful action.

Either you are using DITA as defined or you're defining a purpose-built 
document type for your own business process. That document type might be 
"DITA based" or "DITA like" or "informed by DITA" but it is not DITA 
because it can't be.

That is, if you need a base class that DITA doesn't provide then you've 
established *that you can't use DITA* in the sense that any documents 
you create *cannot be interchanged* within a DITA context, by definition.

That is, DITA itself *cannot be extended* with new base classes--it's 
not a meaningful thing to do within the context of what the DITA 
specification allows you to do. The only thing you can do is specialize 
from the DITA-provided base classes or strict the content rules, but you 
can't add new base classes. Nor would you expect to be able to, since 
DITA-level interchange depends entirely on a fixed set of base types 
(just as any API depends on an invariant set of base classes and methods).

But at least for my clients, that's usually not a big deal because 
interchange *outside the enterprise* at the DITA level is usually not a 
requirement at all or is a very minor requirement relative to the 
requirment to satisfy the local business requirements. Interchange 
within the enterprise is of course in terms of the enterprise-specific 
document type, so that interchange is not impaired.

That's one of the points I'm trying to make: for most of my clients, 
cross-enterprise interchange of DITA-based data is not a requirement, or 
if it is, it has much lower weight than other requirements. Therefore, 
solutions that impair the ability to directly interchange documents in a 
DITA context *are not a problem*. If there is a requirement to 
interchange data in DITA form that requirement can be satisfied by 
providing a non-DITA-to-DITA transform, which be relatively simple, 
especially if the custom DTD is closely based on DITA.

I have to stress: for my clients the primary value of DITA at the moment 
is in the methodology of modularation and aggregation and the notion and 
practice of specialization. But that methodology can be, and often must 
be, applied to non-DITA applications for the simple reason that DITA 
itself as currently defined cannot be made to satisfy the requirements.

But note that we can almost certainly refine the DITA architecture in 
2.0 so that it can be used as the base for most, if not all, modular 
technical documentation applications.

> 
>>I cannot accept this approach as an acceptable solution and would never 
>>suggest it to a client.
> 
> 
> So you'd rather break 100 semantic connections than create one new one? 
> Would using plain nested ph's address your concern? Admittedly nested 
> phrases are generic and without semantic meaning - but that's what 
> specialization adds, after all.

But "ph" has a semantic: phrase. If I use it to create something that is 
not, fundamentally, a phrase, then I've created an invalid and 
inappropriate specialization.

For example, given a body of information, if I say "find all "ph" 
elements" (that is, all elements based on "ph"), and I find something 
that doesn't appear to be a phrase semantically, then I've broken my 
system because I've encoded a lie into it.

That is, as far as I'm concerned, lying about the essential nature of 
your data is wrong and you should never do it. Ever. Under any 
circumstances.

> Ultimately, longer term, we can probably come up with some generic 
> ancestors for each level of content - like <block> as the ancestor for all 
> tables, lists, paragraphs, and figures. 

Here we agree: what DITA needs is probably another layer of 
generalization above the current topic level plus additional generic 
elements in the current topic content models to provide more structural 
flexibility and more generic bases for specialization.

At the same time, there are definitely additional specific types that 
should probably be codified at the topic level so that there is 
agreement and consistency on their use. I would consider having "see" 
and "see-also" elements in the index item markup as a typical example: 
we can probably agree that these are universal semantics that should be 
done consistently across all DITA documents.

   But pragmatically, you can get
> what you want today with a specialization off of <ph> and an override. 
> That's certainly both more cost-effective and more standards-friendly than 
> duplicating the entire set of all existing markup every time you lack a 
> more specific ancestor for that one new element. And when the generic 
> <list> or <block> ancestor materializes, you can repoint your class 
> attributes without affecting any document instances or customized 
> processing you created in the meantime. 

This analysis would be correct *if* re-use of the existing DITA code 
base was a key requirement or if DITA-based interchange was a key 
requirement (and you didn't mind lying about your data). For my clients, 
neither of these are requirements (and I refuse to lie), therefore I 
will not create what I consider to be an inappropriate specialization of 
DITA. If the either of these *were* top requirements then of course I 
might consider it, although I would resist it.

Cheers,

E.
-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(512) 372-8122

eliot@innodata-isogen.com
www.innodata-isogen.com