Sometimes, I run across a document that makes me wonder who is supposed to use it. It doesn’t always seem like the answer is a human being.
Technical documents can be filled with jargon and showy words that make them hard to understand. The tone can be so authoritative or unnatural that any human reader would be turned off to the message. Sometimes, technical documents seem written to impress someone instead of to help others understand.
Poor documentation processes can also result in unusable technical documents. Wrangling documents through a complicated review process with too many stakeholders can produce final drafts that are impossible to understand. When too many people have a personal stake in the details, documents can become collections of “must-haves” instead of usable information. The process doesn’t work if it results in documents that people cannot use!
If people are the intended audience for your documents, then why not write for people? Here are a few of my thoughts about how to do that.
I think most of us are familiar with the feeling of someone talking over our heads. Even if you’re not using big words and technical jargon on purpose, they are barriers for readers to overcome. Use the simplest, most commonly understood words that will convey your meaning.
Euphemisms are another way that you might not be saying what you mean. A good example of a euphemism is saying “certified pre-owned auto” instead of “used car.” Euphemisms are vague, and vagueness is a problem in technical writing. I understand the urge to avoid saying something improper or unpleasant, but it’s more important for readers to understand exactly what you mean.
There’s no need to use a rigid, formal tone in your technical documents. You can write clearly, precisely, and conversationally, even if you’re writing something like a company policy. When you write conversationally, you’re not necessarily writing like you would talk. You’re still using correct grammar and sentence construction. You’re just using more natural language. Here’s an example:
One way to give your writing a friendlier tone is to address the reader directly when it makes sense. There’s really nothing wrong with using the word “you” in technical documents. You can also replace passive voice with active voice. I rewrite what I call pronouncements, which are phrases like “Workers shall…” and “You are prohibited from…”
Organizing a document begins with the scope: what the document does and doesn’t cover. Every document needs a scope, even if you only use it as part of the writing process and won’t include a scope section in the document. All of the information in the document should be relevant to the scope. Information that is outside the scope is clutter, and clutter makes your document less useful.
Organized documents also have logical sections with descriptive headings. Well-written headings mean that readers won’t be confused or surprised by the information they find in a section. They won’t wonder which section contains the information they need.
A clear scope and focused organization can also help you handle “must-have” requests from stakeholders. These requests seem to come from a fear that goes something like “if we don’t include this important information everywhere, we can’t be sure that people will read it.” If the information isn’t relevant to what readers are looking for, they will disregard it. Follow each document’s scope and organization to make sure that important information appears where people will try to find it – the only place it really needs to be.
Writing for humans takes some planning and thought, but if you’re going to be writing anyway, why not write something that people can use?