In the spirit of Elizabeth West's recent tips for better writing,
here's one to consider:
Avoid the gerund wherever possible.
Gerunds are those words in English that end in "-ing." Sentences that
use them tend to feature awkward construction, passive voice, and lack
of conciseness. Gerunds also translate awkwardly in many languages.
Check out this example:
"Installing the foobar package is the only way of making it easy to
change baz configuration."
This is a bit unfair, because I've also mixed in a style problem that
I see many times in gerund-infested material, some of which I've
created myself. Now look at a reconstruction of the sentence:
"To change the configuration of baz, install the foobar package."
What are some of the effects of the rewrite?
* Drops sentence from 16 words to 10
* Increases clarity
* Provides a neutral tone of confident instruction instead of arrogance
* Puts the important material at the end of the sentence, which in
English is the position of emphasis
* Avoids personalizing the instructions too much.
* Avoids making qualitative judgments ("easy")
I always tend to look at gerunds I've written very critically. Far
more often than not, I find they pop up when I lack confidence in an
assertion. Technical documentation should be confident so users feel
they can trust the material.
Hope this helps!
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
Attachment:
pgpuOSeZhHgBf.pgp
Description: PGP signature
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
