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: Martin Jonasson <martinjonassonjobbet -at- gmail -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 08:34:06 -0700

Martin Jonasson wrote:

> Exemple:
> topichead "Alarms"
> - topicref "Concept: Alarms overview"
> - topicref "Fact: List of Alarms"
>
> ... is OK!
>
> topicref "Concept: Alarms overview"
> - topicref "Fact: List of Alarms"
>
> ... is NOT OK as topicref is child of topicref.
>
> He argued that this is the proper way of using topic based authoring and
> would make the information more clear and logic.

I don't know DITA, but if I'm understanding your second (NOT OK) example, it's wrong for reasons having nothing to do with DITA. In outline form, the first example would look like this:

1. Alarms
A. Alarms overview
B. List of alarms
2. Some other topic

The second example would look like this:

1. Alarms overview
A. List of alarms
2. Some other topic

Bad form. A topic shouldn't have a single subtopic. Granted, many of us have occasionally broken that rule when in a hurry, but it's still a good one. I'm a bit surprised that DITA doesn't enforce it.

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

Previous by Author: OT: Wise sayings (was spec writing)
Next by Author: RE: Arguments for NOT using topics as parents to other topics in DITA-maps
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