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: "Janoff, Steven" <Steven -dot- Janoff -at- ga -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>, "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
Date: Thu, 18 Jul 2013 14:08:44 -0700

Comments embedded. Appreciate the exchange.

Steve

Richard Combs 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 have to strongly disagree here. At the DITA shop I worked at a few years ago, we had many instances where a parent topic had a single child subtopic. I believe this was consistent with the spec and our Information Architect guided us in this -- and I thought it made perfect sense. But I've seen and used this structure frequently even in non-DITA environments, such as where we used Flare, or FrameMaker, or other single-sourcing/content management tools. It sounds to me as though you have the same discomfort as with the "widow" and "orphan" situation in publishing and printing -- a minimum of two of something before you'll feel it warrants separation (similar argument below).

>> 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. :-)

Yes, I'm afraid I misspoke on this one. I was actually thinking of the single-step procedure. What threw me off is that in one of my prior gigs, where we had a *lot* of single-step procedures, we would replace the step number, "1)", with a specialized bullet -- I believe it was a sideways triangle pointing right. As you suggest, it was different from the bullet used with bulleted lists. We had many legitimate instances where the single-step procedure made sense. I feel less certain about a single-item true bulleted list, but I can imagine situations where that might make sense. And I would agree with Kevin that creating a workaround to satisfy the need for a "minimum of two" is artificial and wrong.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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


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
RE: Arguments for NOT using topics as parents to other topics in DITA-maps: From: Combs, Richard

Previous by Author: RE: Arguments for NOT using topics as parents to other topics in DITA-maps
Next by Author: Re: How can I phrase this?
Previous by Thread: Re: Arguments for NOT using topics as parents to other topics in DITA-maps
Next by Thread: best simple free HAT for CHM


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

Sponsored Ads


Sponsored Ads