Just a dump of editing stuff for the moment
- Avoid dangling prepositions.
"Note the version you are upgrading from." <-- Incorrect "Note the version from which you are upgrading." <-- Correct
- Avoid personalization ("you," "he," "she") where doing so doesn't
cause unnecessary awkwardness.
"Note the version from which you are upgrading." <-- Not as good "Note the currently installed version." <-- Better
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.
Trim the That
The word "that" is used in the English language most often for indirect discourse, an emphasis on a certain entity we are speaking about to distinguish it from others. Writers easily fall into the trap of using "that" when it does not enhance or add to the message for the reader.
Compare:
This directory contains a folder for each architecture supported by that release of Fedora.
This CD holds a live image that you can use to try Fedora.
The first sentence uses the word "that" correctly, as it is distinguishing there are other releases of Fedora, and we are referring to a specific release. The second sentence has the word "that" as just an extra word. Is there more than one live image on the disc?
Here's a good way to test, try taking "that" out and see if the sentence still makes sense.
This directory contains a folder for each architecture supported by release of Fedora.
Still work? No. So "that" must remain.
This CD holds a live image you can use to try Fedora.
Hey, the sentence still makes sense; without that extra word, the reader is left with a crystal clear message. By the way, the former sentence is another case of where "that" is needed.
So try taking a look over your next piece of writing and see if you can trim the "that." :)