RE: [dita] What Is A Topic

Dana et al.,

I would fully support deprecating nested topics. I believe 
they cause more problems than they provide advantages. They were apparently 
included originally to accommodate legacy documentation. However, I continue to 
advise people to use maps and nesting in maps to accomplish the same thing--to 
show some hierarchical relationship between topics if that is needed for 
readers.

 

When Ginny Redish and I helped Hewlett-Packard develop 
their worldwide Editoral Design System in 1991, we recommended a flat structure 
for user documents. Usability studies told us that elaborate hierarchies of 
topics are essentially lost on users of technical documents. Most readers do not 
distinguish more than three levels of heading at all. 

 

People do not use technical documentation in a way implied 
by hierarchical nesting. They look for the topic they need know and do not 
consider the arrangement. 

 

Elaborate nesting is a leftover from military manuals and 
legal documents that use numbered sections ad infinitum. Even in this context, 
it's not clear what the hierarchies accomplish except to confuse 
readers.

 

Let's define topics as standalone as we have and consisting 
of a minimum content with title and at least one paragraph of text -- that 
should be sufficient. I wonder what others consider a precise definition. 

 

JoAnn

 

JoAnn T. Hackos, PhD
President
Comtech Services, 
Inc.
710 Kipling 
Street, Suite 400
Denver CO 80215
303-232-7586


 

 

From: Dana Spradley 
[mailto:] 
Sent: Friday, December 29, 2006 
9:22 AM
To: 
Subject: Re: [dita] 
What Is A Topic

Personally, I'd like to see the definition of topic 
beefed up and kept in the standard, rather than watered down and demoted to a 
best practice merely.

One of DITA's prime distinctions is being a 
topic-oriented DTD, as opposed to, say, DocBook. Remove that, and you muddy its 
distinctiveness.

On the other hand, I agree with Eliot that 
inconsistencies have developed between nested topics and maps.

Perhaps 
nested topics should be deprecated, and maps promoted as the preferred means to 
collect hierarchies of topics.

If particular organizations still want to 
use DITA against the grain - well, there are always ways to accomplish 
that.

Happy New Year!

--Dana

W. Eliot Kimber 
wrote:

Michael 
  Priestley wrote: 

  On the issue of title-only topics in particular I 
    wanted to add a few things: 

- a small topic may legitimately need 
    only a title and short description - our own glossentry specialization comes 
    to mind. Some forms of context-sensitive help are also likely to be very 
    short, and with the addition of abstract, easily accomodated without the 
    <body> element. 

Hmmm--I'll have to think about this 
  more. 

  - a topic may start small and grow over time into a 
    whole branch of topics. The container topic may be no more than a title and 
    child links (or just a title, with child links managed via a map). But the 
    container topic is still important as a link destination, because it still 
    answers the question it originally answered when it was just a leaf-node 
    topic.  People who link to the topic shouldn't be forced to recode or 
    break their links just because the topic has changed from leaf node to 
    container node. In terms of its subject, it's still the same topic. 
  

This suggests to me that a different structure is needed 
  rather than trying to have topic do double duty as both a coherent direct 
  container of content and as simply a titled container. 

For example, 
  I'm starting to think that it would make sense to allow topichead wherever 
  topic is currently allowed (possibly with a bit of augmentation). This works 
  well in maps so why not allow it in topics as well? [But then would what it 
  mean to have a document whose root element is topichead--not sure and I can 
  imagine that Michael would immediately object to the possibility, which 
  probably he should.] 

On the other hand, I could easily accept 
  Michael's more flexible concept of topic if we, as he suggests, add some 
  discussion of how these two different uses of topic are intended to be used 
  and what would likely constitute abuse of them. 

Clarifying question: 
  When you say: 

"The container topic may be no more than a title and 
  child links" 

Do you mean using links from the related-links section 
  with a semantic of "child"? 

I ask because topic does not allow 
  topicref where it allows nested topics (I originally expected them to be 
  allowed) so I'm assuming that related links is the intended way to create 
  explicit hierarchical relationships from within a topic to other topics. But 
  then that raises the issue of there being three distinct ways to do it (with a 
  map using topicrefs, with links, and with nested topics)--which approach do 
  you choose when? 

This question is somewhat driven by a question 
  related to "what is a topic" which is "when do I use a map to express a unit 
  of re-use (composed of a set of topics that don't have any real individual 
  meaning) and when do I use a topic with nested topics?" 

That is, the 
  implication of Michael's reasoning for having title-only topics that then just 
  point to other topics is that they serve as a consistently-available link 
  target, which is definitely good. But given that I could do the same thing 
  with a map and topichead, which *should* I do? 

If I say "use maps for 
  all collecting of topics" then it leads to the conclusion that there is a very 
  real sense in which the map and the equivalent title-only topic are serving 
  exactly the same rhetorical and practical purpose, which then suggests that 
  either there's a need for a different kind of map that is really a 
  specialization of topic or something. 

But I do keep coming back to the 
  possibility that the distinction between maps and bodyless topics is very 
  slight and that perhaps it would make sense to unify them by allowing topic to 
  allow topichead and topicref where it currently allows nested topics. 
  

I also think that Michael's use case of a topic evolving from being a 
  singular chunk of information to the root of a tree of related topics is a 
  compelling one--it seems not only likely but inevitable. 

However, I'm 
  not convinced that the right solution is simply keeping the original topic 
  around as a navigation target--given an appropriate indirection mechanism (and 
  corrected addressing scheme) you could just as easily replace the original 
  topic with a map (I can't do that today because the *syntax and semantics* for 
  addressing maps and topics is different even though they probably shouldn't 
  be). 

That is, maybe there are really two distinct types of maps: maps 
  that define entire units of delivery and maps that define units of re-use that 
  are functionally equivalent to topics with tested topics and/or topics with 
  child links to other topics. 

To my mind, it certainly seems intuitive 
  to use maps for all organizing of topics and it makes sense from a consistency 
  of tools and work practice, but it doesn't, at the moment, seem to fit as well 
  as it could or should with the current markup design. Thus my quandary. 
  

So I think there's definitely room for refinement in our collective 
  understanding in how to best address these issues of representation of 
  collections of topics that form coherent (and necessary) hierarchies in order 
  to convey a single "true" topic. 

Cheers, 

Eliot