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

["JoAnn Hackos" <joann.hackos@comtech-serv.com>]

I've been listening to this debate with considerable interest. It seems to me that an important issue is being entirely forgotten, especially in an effort to please the client. We find that many of the endless variations of format we find in technical documentation is the result of bad planning or just plain bad writing. Often, the variations are simply a consequence of writers who didn't know what they wanted or were trying to create semantics with no regard for the ability of the reader to understand the distinctions.

 

We generally work with companies to simplify their presentations. The format variations rarely have any genuine purpose in serving the needs of the client. They most often emerge because the writer could not make sense of the information being dictated by a technical expert (who is oblivious to the customer, in most cases).

 

I'm very concerned about a consulting approach that tries to maintain all the variations that have over eons been imposed on a documentation set. Behind this is the nemesis of "conversion" rather than rethinking, simplification, and minimalism. Perhaps clients would be better served by working with a design consultant rather than trying to convert all previous format quirks into DTDs. Most of these nested lists and subparts or subparts carry no advantage to the reader. We try to point out to clients that they really don't need to write that way.

 

JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
joann.hackos@comtech-serv.com
http://www.comtech-serv.com

 

---

From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, December 07, 2004 6:37 PM
To: W. Eliot Kimber
Cc: DITA TC list
Subject: Re: [dita] When does DITA Document Type Not Meet Requirements?

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

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

Re: 
>> Re the untitled containers within a topic: why didn't 
section work for 
>> you?
>
>Because I need containers that 
are peers to topicbody, not within 
>topicbody. 

You'll have to expand the example for me to comment on 
this. 

Michael 
Priestley
mpriestl@ca.ibm.com

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

12/07/2004 05:44 PM

To	Michael Priestley/Toronto/IBM@IBMCA
cc
Subject	Re: [dita] When does DITA Document Type Not Meet Requirements?

Michael Priestley 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.

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.

I 
cannot accept this approach as an acceptable solution and would never 
suggest it to a client.

> Re the untitled containers within a 
topic: why didn't section work for 
> you?

Because I need 
containers that are peers to topicbody, not within 
topicbody.

> 
Another side note: are you okay with this discussion happening on the 
> 
side? I inadvertantly hit reply to you individually on my first reply. 

I'd rather it happened on this list so others can learn and 
participate.

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