Many people want to be good writers. It is a central skill because so much of our communication is done through written channels. Everything from technical documents to emails to tweets requires writing.
Unfortunately, some regard writing as an almost mystical process where inspiration flows from your soul onto the paper where it emerges whole, perfect, and sacred. Thinking about writing this way is convenient, because then your crappy writing is the muse’s fault. But it’s more effective to realize that good writing is rarely beautiful at first. Writing is more like making a sculpture out of clay: you start with a big pile of mucky dirt (the first draft) that you have to mash all around (in a text editor) to get it to look like what you want it to look like.
Like the sculptor, the writer must master the tools—-in this case, words. But mastering words is more abstract than mastering sculpting tools, leading some people to think that mastering words must be an in-born talent that can’t be otherwise learned.
Effective use of words can be learned, though, if the aspiring writer is dedicated, disciplined, and willing to make a whole lot of ugly sculptures en route to making a beautiful one. The fact that you created many unrecognizable blobs when learning the medium might not be romantic, but it doesn’t detract from the artfulness of your eventual works of art.
Skill #1: reducing word count
You know the goal of good technical communication is to make the user successful with your product, and your higher-ups probably know that too. But “making the user successful” is hard to measure, and execs like numbers, so chances are, they’re going to be impressed by your page count.
While it may be satisfying to you to thump a thick manual down on the VP’s desk, the user faced with that tome is going to freak out. Plus, it’ll cost a fortune to translate.
Scope – what does the reader need to know?
Fortunately, you can impress your executive and serve your user at the same time by differentiating between “documentation” and “help.”
Documentation is the exhaustive, authoritative, single version of the truth that covers your product soup-to-nuts and may be a legally binding statement of what your product does. Documentation can be a massive, encyclopedic resource for requirements, test cases, and support calls. Writing documentation is time consuming, but it is a relatively straightforward process to create.
Help is what you’d tell the user if you were sitting next to them while they are using your product. Help should be as brief as it can effectively be so the user doesn’t have to wade through extra information to find what they need. Writing help is hard: it demands deep understanding of users and their goals so you can anticipate which questions to answer. This is where you earn your money, and though help is shorter than documentation, it will probably take you longer to write.
Unnecessary words
Maybe it’s because I’m in the Midwest and it’s against our culture to be too direct, but I see many writers who are just not comfortable saying something in a straightforward way, so they add a bunch of words to soften the message. When I was working on my MBA, I’d have arguments about this in group projects: my group would agree that my draft covered everything, but they’d feel like it “just needed more words.” Then someone else in the group would add a bunch of words to fluff everything up.
True, it led to a thicker binder to turn in, but it didn’t say anything more than it did before. If I were the professor, I’d be mad that someone made me read twice as much to say the same thing, but that’s academia for you.
In technical communication, there are some words that never need to be said. If you’re in the habit of typing these filler words, find-and-replace-and-kill-with-extreme-prejudice.
“Please” – If you’re asking the reader for a favor this is polite (“Please let us know if you found this document helpful”), but when you are answering a question, why would you say it? In real life, when your significant other says, “Honey, where’s the remote?” do you answer with, “Please check the coffee table or top shelf of the refrigerator”?
“Easy” – No one cares about your opinion of how easy your product is. If it is so damn easy, why are you writing help? What do you expect to happen when you tell the reader that your product is easy? Are you imagining some poor, hapless soul out there who is timidly flipping through the documentation before daring to use the product and who, upon seeing your claim that it is easy will say, “Oh, thank goodness! Now I’m not afraid anymore!”
“Various” – What, precisely, is the difference between saying, “these are the various items in your folder” and “these are the items in your folder”? When removing a word doesn’t change the meaning of a sentence at all, cut it. Unnecessary words are nothing but noise, translation cost, and an opportunity for typos.
Skill #2: inverted pyramid construction
Technical documentation and journalistic articles have a lot in common: they communicate facts, don’t spare much time for flourishes, and are more focused on the reader than on the writer. Another thing that a user-focused piece of help ought to have in common with a journalistic article is the inverted pyramid construction.
For those of you who missed Journalism 101, the inverted pyramid refers to putting the most general and important facts first, followed by increasing specific and expendable details. Accomplishing this requires time and thought. It might take you only 15 minutes to type a document, but it could reasonably take you the rest of the hour to re-read, reorganize, and reconsider what the user really needs to know most.
Having to tear apart what seems like a perfectly good document to see what it will look like in a different order can cut a writer to the quick. If you’re queasy, using a tool with good revision history (softball to MindTouch) can make it easier to take that leap into ripping up your own content.
Skill #3: second person, present tense, active voice
I’m way into the realm of techcomm 101 here, but mastering your tools demands that you cover the basics, and I’ve known plenty of experienced writers who haven’t built this strong foundation.
Second person
Call the reader “you.” You’re sitting next to this person helping them out…clearly you’re buds and there’s no need to be too formal. If you are writing for an audience who is doing work for an audience (like, if you’re writing for developers who are programming for users of their own), call their users “the user.” That helps keep things straight.
Present tense
Writers who have trouble staying in the present tense usually slip into the future. So, rather than saying, “click the button and the window appears,” they say, “click the button and the window will appear.” Not only does present tense use fewer words and communicate that this is how the product works now, but sometimes you really do need to use the future tense. For example, “ will be supported in the next release” is a time when there’s a genuine need for the future tense. If you’ve been using the future tense all along in your documentation then this real need for the future tense gets lost.
Active voice
Clearly there are times when the passive voice is appropriate, but generally saying, “when the button is clicked, a window appears” when you mean “click the button to open the window” just leaves the reader wondering who’s supposed to be doing what. Again, think about what you would say to a person if you were sitting next to them helping them through the process.
In summary
Writing is like any art: everyone can do it, but not everyone can do it well. Even though it is an art, there are skills you must master, and the fact that the practice, self-analysis, and intentional thought you do to master them is ugly does not diminish your ultimate masterpiece.
What techniques have you used to master your writing domain? Feel free to share them in the comments below.