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] What Is A Topic

Grosso, Paul wrote:

>  don't disagree with Eliot and Scott that the wording about
> topics could perhaps be clarified a bit, though I consider
> that mostly editorial and not a substantive issue in the spec.

That may be the intent but the fact is that it's in a normative section 
of the specification and, given that there is no other formal definition 
of "topic", it must be taken as the normative definition of what a topic 
is. One solution would be to rewrite the sentence to make it less 
definitive, i.e.,

"A topic is usually taken to be a unit of information with a title and 
content, short enough to be specific to a single subject or answer a 
single question, but long enough to make sense on its own and be 
authored as a unit."

But I think the fact that Paul and I could even have this difference of 
interpretation points to a problem with the specification as written, in 
that it is not nearly as formal as many of us have come to expect 
standards to be (especially those of us raised in the Charles Goldfarb 
school of Standards Written By Paranoid Harvard-Trained Attorneys).

DITA, by it's nature as a generic, enabling, application standard is 
inherently fuzzy but that shouldn't give us license to leave unclear key 
distinctions and definitions.

For example, it's clear that both Michael and Don D. have clear, and I 
think, consistent ideas of what is and is not a topic, but it's not 
clear to me that those ideas are either definitive (that is, do they 
match the *community's* idea of what is and is not a topic) or crisply 
conveyed in the specification. But the issue of what is an is not a 
topic is clearly of central importance to DITA, both as it's used within 
IBM and as its understood by (or imposed on) the larger DITA user 

> If there are really good reasons why it is actually worth the
> effort to retag it using DITA, then by definition, there should
> be good reasons to *rewrite* it in a topic oriented fashion rather
> than trying to cram non-DITA-isms into the DITA mold.
> Perhaps I'm over-reacting to the word "legacy", but I think we
> need to consider extensions to DITA in light of actual topic
> oriented related requirements rather than conversion issues.

I generally agree with Paul, except...

In my case, the legacy is unstructured documents that reflect a 
long-established practice within an industry. So while everyone involved 
agrees that the writing approach may not be optimal, it's also not 
necessarily possible or practical to completely change the structure and 
approach of the documentation as cost of entry to the use of DITA (which 
is otherwise clearly indicated in this case).

So that leaves the problem of how to do an *initial* mapping of the 
legacy to DITA structures with the minimum amount of disruption to the 
existing structures while being as true as possible to both the intent 
of DITA and the letter of the specification as well as to established 
practice (to the degree that there is any for DITA).

That is, while I agree that ideally all uses of DITA should reflect the 
best of minimalist practice, for DITA to be widely applied it must make 
some allowance for the practical challenges of legacy data and the sheer 
cost involved in migrating a large existing body of documents and 
established authoring practice to an often radically different way of 
doing things.

And again I must apologize for raising these issues now and not a year 
ago--it's just an accident of my personal work history that I didn't 
have the opportunity to address these sorts of issues in a real context 
before now. I'm definitely not suggesting we change the DITA model at 
this time, but I think we still have time to tighten the spec as written 
and prepare for more in-depth discussions in the 1.3/2.0 time frame.

But I think these questions also reflect the nature of the original DITA 
definition, which was not intended to be anything like a formal standard 
but to document the basics for a body of authors who shared a common 
culture and for whom a lot of the DITA wisdom and knowledge was received 
from collegues. By contrast, DITA the standard is a formal standard and 
needs to, as much as possible, stand alone. I know we can't expect 
something as legalistically formal as a Goldfarb standard in the 1.1 
time frame (Michael is human, after all) but we still need to try to 
make it as clear and precise as we can.


W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(214) 954-5198


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