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.
Jeff Jansen wondered: <<I'm developing a template in Microsoft Word
for a client... It makes sense to organize the document such that
several sections of a document each have a subheading for each ECM in
the building. The problem is that some buildings have only a single
ECM, so the documents for those buildings would have some headings
with only a single next-level-down subheading. This is usually
considered a violation of document-structure conventions, so I'm
asking for advice on how to deal with this situation.>>
Some style guides frown on this, just as they frown on having a main
heading followed immediately by a subheading, with no intermediate
text. It's true that in both cases, there are often reasons to avoid
this (both can be symptoms of structural problems and a need to
collapse or simplify the heading hierarchy for a section), but in
general, neither is a major sin from a practical perspective (i.e.,
from usability of the document by the user).
More to the point, since the idea of a template is to help writers
present readers with consistent content, your note that "I don't
think merging the subheading copy with the heading copy (that is,
omitting the subheading altogether) is appropriate" is right on the
money. In a one-off document, that would be a good approach, but for
a document series in which consistency is important, it's not the
best solution.
An alternative solution would be to add a subheading to the template
to ensure that every document has at least two subheadings in the
section you're discussing. In most cases, this would just be
unnecessary filler, but if you can think of some standard information
that really does belong in the ECM section (e.g., standard
definitions, standard cautions or warnings), then there's a good
justification for this. But don't add that subheading unless it truly
serves a useful purpose.
Yet another alternative would be to change the main heading to "ECM
information for [building name]". Then, if there is only one ECM,
there would be no subheadings; if there are two or more, each would
get its own subheading. Problem solved! But that's more complicated
to implement, since you need to include the subheadings (e.g.,
"ECM1", "ECM2", etc.) in the template for buildings with more than
one. Though you can instruct writers to delete these subheadings when
they're not used (http://www.geoff-hart.com/resources/2000/
dynamicstyle.htm), some authors will inevitably leave one or more
headings in place. Still, assuming there will be editing or other
review processes, these problems should be easily caught.
----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
