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.
Good points below. However, my sense is that we can easily resolve most
points on writing and grammar by following Jack Valenti's advice. This,
IMHO, applies to *all* kinds of writing:
"Keep it short, sharp and punchy."
Examples
Longer, duller, more complex:
"A confirmation dialog will appear."
"Keep it very short, extremely punchy, and it will ensure readability to
make it appear sharp as well, in order to suffice the needs of a reader to
avoid ungainly and overly dramatic nuances which cannot, of themselves, be
secured or ignored--so as to say, rather imperfectly as it were; and for
this, my sincerest apologies--in order to form a more perfect
understanding."
Shorter, punchier -- it makes the sentence *move*:
"A confirmation dialog pops up."
"Keep it short, sharp and punchy."
You could make an exception for a piece in a piece when you intend to lull
the reader to sleep along with the protagonist. A long, meandering
sentence, stuffed with adjectives and passive voice could mirror a sleepy
or dull tone you want to convey. Or such a sentence could describe a
particularly uneventful day or place, mirroring the feeling in words.
Tim Mantyla
NOTE: The only other kind of writing Valenti's advice does not apply to
are entries in The Bulwer-Lytton Fiction Contest. The contest is inspired
by and named for English novelist Bulwer-Lytton's lead sentence in "Paul
Clifford," quoted below. The prize-winner writes the worst, most
convoluted first sentence to an imaginary novel. Absolutely hilarious!
www.bulwer-lytton.com/
"It was a dark and stormy night; the rain fell in torrents--except at
occasional intervals, when it was checked by a violent gust of wind which
swept up the streets (for it is in London that our scene lies), rattling
along the housetops, and fiercely agitating the scanty flame of the lamps
that struggled against the darkness."
--Edward George Bulwer-Lytton, Paul Clifford (1830)
> J Wermont wrote:
> > McLauchlan, Kevin wrote:
> >
> > (I'm much more averse to the
> > > use of "will" than to the very occasional passive construction.)
> >
> > May I ask why? I hear this often, but I have never understood what
people
> > are objecting to. The following makes perfect sense and sounds fine to
me:
> >
> > Click the Delete Tag button at the bottom of the page. A
confirmation
> > dialog will appear.
> >
> > It makes sense to me because at the time the user is clicking the
Delete
> > Tag button, the appearance of the confirmation dialog *is* in the
future.
> > So why not use the future tense?
> >
>
> It isn't in the future any more than clicking the
> button is in the future. When you click the button,
> the dialog box appears. It's cause and effect in
> the same time frame. Procedural writing assumes
> that readers are following the instructions and
> performing the actions in sequence. Therefore, the
> reader reads the action and clicks the button. The
> next thing that happens from the perspective of the
> readers is that the dialog box appears right before
> their eyes as they're watching, not in the future.
>
> Click the Delete Tag button.
>
> A confirmation dialog box appears.
>
> -- Janice
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
