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

I'm really struggling with the issue of what is and isn't a topic (or 
rather, what should and shouldn't be a topic). This is partly a side 
effect of trying to answer the question of whether or not section w/in 
topic body should nest and partly a side effect of trying to decide how 
best to map a client's legacy documents to topics.

In particular, I'm struck by the apparent conflict between these two 
statements from the architectural specification:

 From What are Topics?:

"A topic is 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."

And from "Transitional Text Workarounds":

"A DITA topic can be as minimal as just a title,...."

Which is certainly true by the current DTDs.

But this strikes me as odd, namely a topic that consists of only a title 
cannot possibly satisfy the requirement that it "make sense on its own".

Likewise, the initial definition of topic says "title *and* content" (my 
emphasis) which certainly seems to require that topics have content.

Certainly within a map it makes sense to be able to have a topichead 
that is just a hierarchical level with a title but no direct 
content--this happens all the time in docs [whether or not it's good 
editorial practice is a separate question] but it seems to me to be 
diluting meaning of "topic" to allow or condone topics that consist of 
only titles.

But clearly there is a body of either thought or practice, at least 
within IBM, that considers a topic that is just a title to be OK.

To my mind, it seems that DITA is best served by taking a fairly strict 
view of what is and is not a topic and I focus in particular on the 
"make sense on its own" aspect of topics, as given in the initial 
definition of "topic".

By the same token, it seems to me that if you are willing to allow 
topics to be as small as possible (i.e., <topic><title/></topic> that 
you would be willing to allow topics to be arbitrarily large as well, as 
long as they satisfy the constraint of "specific to a single subject".

But in absence of a clear definition of what is and is not a topic, I 
don't see that we have any basis for objective judging of what is or is 
not a topic.

At a minimum, I think the specification needs to be internally 
consistent on what the explicit and implied rules for topics are. At the 
moment, the specifications and statements such as the second one are 
inconsistent with the initial (and primary) definition of "topic".

Either we have to disallow title-only topics (which I don't think we can 
do at this point since we have to be backward compatible with 1.0) or we 
have to relax the initial definition to make it clear that topics are 
not required to have bodies nor are they required to make sense on their 
own, but can in fact be just titles.



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]