RE: Arguments for NOT using topics as parents to other topics in DITA-maps

Subject: RE: Arguments for NOT using topics as parents to other topics in DITA-maps
From: Steven Jong <stevefjong -at- comcast -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sat, 20 Jul 2013 13:07:39 -0400

As an old-school writer, I agree that having a single subheading, like having a single-item list, is bad organizational form: if there's only one instance, it doesn't merit being split out. However, as a new-age worker in environment of intensive topic sharing, I find single-item lists and subtopics unavoidable. It has nothing to do with DITA or information architecture, but with topic sharing and products modes.

For example, I document a product that comes in different modes for different kinds of telecom carriers (wireless, cable, fiber-optic). In one mode, you can define a goodly variety of network elements. The information structure is something like this:

Managing Network Elements
About Network Elements
Defining a Network Element
This Element
That Element
Some Other Element
Editing a Network Element
Deleting a Network Element

In another mode there aren't as many network elements, so the list is shorter. And in one mode, there's only one kind of network element. Logically, if that's the only mode I was documenting, I would have one topic, called "Defining the Network Element." But I am sharing most of the topics, and they are identical across modes. I don't want to have multiple structures to account for the single subtopic in one mode; I would rather break the organizational rule.

The same situation applies to bulleted lists. By retaining the structure and presentation, sometimes (if rarely) we end up with a one-item list.

(For the record, I would most prefer to use structured documentation techniques and have only first-level heads in my document! But the formatting I have to work with is so limited that I've scaled back my ambitions.)

New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more:


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: RE: What to call this thing?
Next by Author: Re: Master Documents in Word
Previous by Thread: Re: Comma question
Next by Thread: OT: waterproof Bluetooth keyboard recs?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads