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: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: "Janoff, Steven" <Steven -dot- Janoff -at- ga -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 17 Jul 2013 19:12:50 -0700

Janoff, Steven wrote:

> Richard, can you expand on your objection to a topic having a single subtopic?
> I'm trying to understand what you mean by "bad form."

It's a logically flawed way of organizing concepts. If the "umbrella" topic properly encompasses only one item, that item is the "umbrella" topic and shouldn't be a subsidiary of it. If the "umbrella" topic and the item it contains are separate topics, they should be at the same level under an "umbrella" that encompasses both.

> I'm reminded of the idea that a bulleted list shouldn't have a single bullet.
> Although it doesn't look great, it's sometimes necessary, even when there's
> enough time for reflection.

Why do you think it's sometimes necessary? This is clearly wrong, IMHO -- more so than a single subtopic. Why would you ever need or want to create a list if there is only one item to list?

Note: I'm speaking of unordered lists, primarily. I exempt from my objection the single-step procedure. If the document convention calls for every procedure to begin with a recognizably formatted "To do X" type of heading, followed by a numbered list of steps, it's probably best for consistency to mimic that, but follow the heading with a single step with a unique bullet (different from unordered list bullets). But I also think single-step procedures can almost always be turned into two-step procedures if you're half-way clever. :-)

Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-903-6372
------








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

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
Arguments for NOT using topics as parents to other topics in DITA-maps: From: Martin Jonasson
RE: Arguments for NOT using topics as parents to other topics in DITA-maps: From: Combs, Richard
RE: Arguments for NOT using topics as parents to other topics in DITA-maps: From: Janoff, Steven

Previous by Author: RE: Arguments for NOT using topics as parents to other topics in DITA-maps
Next by Author: RE: Comma question
Previous by Thread: RE: Arguments for NOT using topics as parents to other topics in DITA-maps
Next by Thread: Re: Arguments for NOT using topics as parents to other topics in DITA-maps


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


Sponsored Ads