I’ll never forget the strangest criticism someone once gave me about a software manual I had written: “Your writing is too user-friendly.” What she intended as criticism, I considered a back-handed compliment. That manager was from the old school of technical writing. She believed that technical writing should be formal and never use the second-person voice (“you”).
However, the goal of technical writing is to convey facts in a clear, concise way to your audience. If your writing is stilted, your audience will stop reading. That’s why my philosophy is: write as you speak (almost). If you adopt a natural, conversational tone when writing—without the slang and rambling, of course—your audience will be engaged because they can “hear” your voice when reading.
After reading my introduction to that same software manual, a user told me: “This is the first time I ever understood what this software does.” That user was my audience. So I knew that manual had accomplished its goal.
Here are some tips to help you write as you speak:
- Read each paragraph aloud and note whether it sounds natural.
- Use the fewest number of words to convey the idea.
- Use the simplest word that conveys the idea (“use” not “utilize”).
- Use the second-person voice (“you”), not third-person voice (“the user”).
- Use the active voice in constructing sentences, not the passive voice:
“Push the power button” not “The power button should be pushed.”
- Use the present tense instead of the future tense, when practical:
“The screen opens” not “The screen will open.”
From the old school of wordy, passive-voice technical writing:
The keyboard should be positioned correctly to avoid unnecessary strain on the hands. The power button should be depressed by the system administrator. In a few moments, the Welcome screen will open. The correct username and password should be entered in the appropriate fields.
From the new school of concise, active-voice technical writing:
Position the keyboard comfortably to avoid hand strain. Push the power button. After the Welcome screen opens, type your username and password.
People sometimes joke, “Well, no one reads the manual anyway, so what does it matter?” I agree that people don’t usually read manuals or other reference materials until they need to. But when people do have questions or want to understand something, they will read the material provided and they expect it to be understandable and well-written.
© 2012, Sandra Elam. All rights reserved.