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.
Ellen Vanrenen wonders about some style guide recommendations: <<Keep your
words, sentences and sections short.>>
A better rule would be: "write simply and directly, and include only the
necessary information". I don't recall what genre of writing you're doing,
but short words are often the wrong words (know thy jargon!),
well-constructed long sentences are often more communicative than
artificially short ones, and a section's length is dictated by the content,
not by an arbitrary goal of shortness. Simplicity is more virtuous, since
the really great writers can make even complex concepts relatively easy to
understand.
<<The rule of thumb is 7 items per section. Anything longer is harder for
the reader to absorb.>>
This red herring results from a misunderstanding of George Miller's research
on the "magic number 7", which relates only to short-term memory and thus
has much less relevance to technical writing than many people think.* In
practice, a section should contain as many "items" (whatever those are) as
required to bring the reader from a logical starting point to a logical
point at which they could pause to draw breath. For example, a complex
installation procedure that totals 200 steps might well require the reader
to finish the first 50 steps in a single, uninterrupted sequence, with no
logical places to pause. The remaining 150 steps might well break into
groups of 7 to 20 steps, but that depends on their contents, not on
arbitrary numbers.
* About the only place that comes to mind, offhand, is when you present a
series of alternatives that the reader must hold in their head
simultaneously for the sake of comparison; then, short-term memory is
intimately involved, and you do need to reduce the number of items the
reader must juggle simultaneously. But when you encounter such a situation,
it's often better to come up with an if/then decision chart of some sort
that lets the reader instantly discard the irrelevant options so they can
focus on the relevant ones.
<<If your document runs much longer, consider dividing it into logical
segments>>
Strike the first part of this rule, and make the last part specific: "Divide
the content into chunks so that each chunk begins at a clear starting point
and ends at a point where the reader could logically pause before
continuing."
<<I tend to think having a lot of headings with short paragraphs would force
you to simplify>>
The relationships between headings and paragraphs isn't easy to quantify.
The trick is to think like an indexer, and have a clear idea of what the
main topics and subtopics are; this is based on the semantic content, not on
the number of paragraphs. Once you can divide the information into these
chunks, you can develop headings that support this structure. Don't forget,
one important goal of headings is to help readers scan down the page to find
the right section; if you clutter a page with too many headings, you thwart
that goal.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"How are SF writers like technical writers? Well, we both write about the
things we imagine will happen in the future!"--Sue Gallagher
Planning to attend IPCC 01, October 24-27 in Santa Fe? Sign up by
October 3 and get a substantial discount! Program information,
online registration, and more on http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.com +++
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
