TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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:Editor in Chief <editorialstandards -at- gmail -dot- com> To:"Combs, Richard" <richard -dot- combs -at- polycom -dot- com> Date:Thu, 18 Jul 2013 09:29:41 -0400
-----Original Message-----
From: Combs, Richard
[replying to 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.
**** This part (above), I agree with. *****
>> 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. :-)
[snip]
I don't see that at all.
If there's plenty of precedent for a certain style of heading plus a small
intro paragraph, followed by a bulleted list, including perhaps some
examples immediately above and below on the same page, and then you get to
a new category that gets a new heading and little intro paragraph plus...
oh... there's only the one item... looks like it'll be a one-bullet
"list". It certainly looks better than making up a bogus second item (like
a product feature that doesn't exist...?) , or adding a second item that
says:
- this otherwise unnecessary item added to satisfy the sensibilities of
R. Combs, esq. :-)
As for the numbered lists, if an operation is one step, especially if it's
the new version of something that formerly wasn't so streamlined, then it's
one step. If you have to be "clever" to make up a bogus step, or if you
resort to breaking a one-step process into two or more, when all the nearby
procedures have avoided that unnecessary level of "For extra-dumb Dummies"
fragmentation - or worse, if you now have to go back and insert baby steps
into all the other nearby procedures, just so they'll match the level...
Ohfergawdsake just leave the one-step procedure and get on with life.
If you have an end-user customer who would seriously object to the one-step
procedure, you are probably the first. Ever.
If you have a reviewer who objects to the one-step procedure, you have
found a volunteer to re-write anything nearby that doesn't fit their
favored scheme that they want inserted here. Tell them that, in so many
words. Tell them you'll use their replacement section/chapter/whatever if
it's ready and perfect before your release deadline; otherwise your
one-step version is what gets shipped. Look pointedly at your watch (if
you still wear one).
If you actually get the near-mindless retort "You're supposed to be the
writer. Can't you figure it out?" then your response is "I'm not the one
imposing witless requirements on a tight project schedule. I could do it if
I cared to take the time and cared to try to justify doing something
utterly frivolous at this point in the schedule. But you are the person who
wants it enough to have made a point of it, and who asserts that it's easy
to do or that there's plenty of time (in your version of the project
schedule) to do it. So you and your sneer just volunteered. Get back to me
with the finished version no later than xxxxxxx. Right now, I have actual
work to do.
>
--
__o
_`\<,_
(*)/ (*)
Don't go away. We'll be right back.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
