Reading technical documentation is nobody’s idea of an enjoyable night in. You could try to make it special with some wine and candlelight, but it’s still going to be a stretch. Therefore, the documentation needs to strike that balance between being complete while using as few words as possible. If you use too many words, no one will want to wade through it to find the information; if you use too few words, the information won’t be complete or useful.
Flexing your Vocabulary
One of the ways to strike that balance is shorten sentences by using strong verbs, descriptive nouns, and common language. While the written word and spoken language are two different beasts, you can often simplify words and sentences by asking yourself “If I were explaining this to someone, is this the word I would use? Who speaks this way nowadays?”
For example,
BAD: “In order to reduce obscurification, one must employ the appropriate level of verbiage that targets the desired balance of plenitude while being spartan in the use of colloquialisms.” (I almost fell asleep in the middle of writing that sentence.)
BETTER: “To ensure written clarity, you need to strike a balance between being complete and using a minimum of words.”
BETTER: “Make sure that your writing is clear and complete by picking your words carefully, crafting your sentences to be short and strong, and remove any language that drags.”
TOO MUCH: “To be clear, don’t use too many words.” — This tells the reader what to do, but not how to do it.
Reduce your Phrasing
While trying to sound literary the way Ms. Crabapple always insisted, writers sometimes pad their sentences with too many introductory words. More words do not make you look smarter: being smart and mindful when using strong, snappy words make your sentences come alive.
The following are some common phrases that I’ve seen that can be reduced easily, making for stronger, punchier writing:
- In order to run: To run
- Whenever you want to run: To run
- It may be desirable to run: You may need to run
- In order to utilize your running shoes: To use your running shoes
- Please select the following running shoes: Select the following running shoes
(I know it seems rude, but never politely beg the user to following the instructions) - A large number of people run: Many people run
Passive Voice
When possible, try to avoid using the Passive Voice. In the Passive Voice, the subject that is performing the action is unclear, so you end up with long sentences that jump around to avoid naming anyone specific. You can get around this by speaking to the reader directly using the 2nd person voice (You).
BAD: “The required information is acquired upon successful application of sufficient force to the button.”
BETTER: “To get the information you need, press the button.”
BETTER: “To get the information, you should press the button.”
BETTER: “To get the information, press the button.”
There are times when using the Passive Voice is unavoidable. Therefore, it should be used sparingly. Er, I mean… *you* should use the Passive Voice sparingly.
