dita — archive

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

From: JoAnn Hackos
To: [email protected]
Date: Wed, 08 Dec 2004 12:49:00 -0000

MHonArc v2.5.0b2 -->

dita message

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

From: "JoAnn Hackos" <[email protected]>
To: "Michael Priestley" <[email protected]>,"W. Eliot Kimber" <[email protected]>
Date: Wed, 8 Dec 2004 05:51:05 -0700

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
[email protected]
http://www.comtech-serv.com

From: Michael Priestley [mailto:[email protected]]
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
[email protected]

"W. Eliot Kimber" <[email protected]>

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 [email protected] www.innodata-isogen.com

Follow-Ups:
- RE: [dita] When does DITA Document Type Not Meet Requirements?
  - From: Deborah Aleyne Lapeyre <[email protected]>
- Re: [dita] When does DITA Document Type Not Meet Requirements?
  - From: "W. Eliot Kimber" <[email protected]>