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.
Taken completely out of context, for the purpose of veering off on a tangent:
>Every flavor of writing might use "basic" writing skills, but if I'm doing
>step-by-step instructions, I'm less concerned about run on sentences,
>passive voice, and dangling participles...
When I write concise, informative procedural steps, these are *precisely*
the things I find myself taking into account. Or, conversely, when I read
or edit procedural steps written by other writers, these are the types of
errors I encounter more often than I would expect.
I believe that writing clear procedures is an art form in itself. I'm not
saying that this makes it a completely creative endeavor; rather that
writing clear steps is an exercise in what I call "creativity within
constraint." In other words, I see it as my mission to convey complex
technical information in the most concise way, to reduce that complexity to
a series of actions to perform in a linear sequence, and to use a
well-defined, predictable structure to do so.
What makes poorly written procedural steps confusing is a combination of
the three grammatical constructs mentioned above:
* Run-on sentences; for example, where the writer did not effectively break
down the task into individual chunks, each of which contains a single
instruction. Too many times I have seen conceptual information mushed in
with the action I am supposed to take, rather than breaking these into two
ideas: a brief description what is going to happen next, followed by a
clearly worded instruction.
* Passive voice; for example, when a step is worded in such a way that it
is ambiguous whether I am to wait for the software to perform an action, or
whether I need to do something myself. For the most part, I find active
voice more effective in procedural steps. I am *not* saying that passive
voice is evil or always to be avoided. I have used it many times myself,
but I endeavor to choose carefully based on the context.
* Dangling participles; for example, this construct is often the result of
using a less-than-precise word to describe either an action or an element
of the process being documented. I have often found misplaced modifiers
in procedural steps where there is inconsistent terminology or syntax from
one section to the next, or in different procedures within a documentation
set.
In any case, my point is that being aware, even at an unconscious level, of
basic grammatical constructs can prevent many of the problems I've seen in
confusing or poorly written procedures. When I write a set of steps, I
read them aloud to myself, looking for these and other stumbling blocks,
and I reword the sections that are imprecise or awkward.
As I've read often on this list, I don't believe in being a slave to
grammar, but I do believe that the more aware I am of the principles of the
language, the more I can make informed choices as I write.
martha
--
Martha Jane {Kolman | Davidson} mailto:editrix -at- slip -dot- net
"If I am not for myself, who will be for me?
If I am only for myself, what am I?
If not now, when?"
--Hillel, "Mishna, Sayings of the Fathers 1:13"
