by Jean Hollis Weber
Business Consulting News, October 1997, a web magazine (address no longer valid).
The short answer to this question is: just about everyone who needs to prepare written technical material.
As a successful consultant or business owner in a technical field such as engineering or computing, you probably need to prepare a variety of documents, including proposals, progress reports, user guides, technical manuals, procedures, instructions on the use of equipment, and so on. You may also need marketing and presentation materials, such as brochures and specification sheets.
If you’re in this situation, you know that you can’t do everything yourself. Even if you were an expert on all aspects of running your business (not just an expert on the product or service you’re providing), you simply wouldn’t have the time. So you pay other people to do some of the work for you. You may hire staff or outsource the work to another professional, such as an accountant.
However, if you’re like most consultants, you probably do your own writing, or your technical experts do it. Why? It’s probably not because you’re an excellent writer; but even if you are, you probably have better things to do with your time. Perhaps you do your own writing because you think it’s too difficult or time-consuming to pass the information on to someone else to do the writing for you. Perhaps you are unaware of the wide range of skills that a professional technical writer has to offer. Perhaps you think hiring a writer is too expensive. Perhaps you’ve had a bad experience with a writer in the past. Or perhaps it’s never occurred to you to use a professional writer’s services.
I suggest that the right technical writer can add a great deal of value to your business and probably save you money in the long run – or even bring in extra money. In this article I’ll look at some of the most common problems in materials written by non-writers – problems that can cost you money. You may fail to make a sale (or get a contract) if the customer doesn’t understand your proposal. After the sale, you or your staff may have to spend a lot of extra time explaining things to customers, if they can’t understand the instructions.
As well as materials for customers, you need to document your own procedures and those of your company, for internal use and as part of your disaster recovery plan. Consider what would happen if a key employee, perhaps the only person who understood some vital part of your business, died tomorrow without leaving a written record of that part of the business. How long would it take to reconstruct that knowledge? How much would your business suffer in the meantime? You could probably recover using poorly-written or out-of-date documents, but you’d waste a lot of time that you can’t afford.
The most common writing problems
Here are some of the most common writing problems found in technical documents, whether printed or online. Click on a highlighted topic for more details.
Writing that’s wrong for the audience
- Too much detail, too little detail, or the wrong details
- Jargon, technical terms, and other language at the wrong level
- Assumptions about previous knowledge
- Telling people what you want to tell them, not what they want to know
- Logical sequence from the writer’s point of view, but not the reader’s
Experts in almost any field have difficulty in explaining specialist concepts to non-experts. It’s too easy to forget that what’s common knowledge to you (or me) is quite unfamiliar to someone else. It’s also easy to go too far in the other direction and forget that non-experts may know the concepts, but not the terminology, so you run the risk of talking down to them if you simplify too much. An ideal writer for this situation is one who knows what the intended audience knows, and just enough of the subject matter to ask intelligent questions of the technical experts and interpret the answers for the audience.
For example, if you’re providing an accounting program aimed at qualified accountants, you don’t have to explain accounting to them; in fact, it would probably be insulting to do so. But you do need to explain how to use your program to accomplish their tasks. The accountants probably don’t want to know how the program works internally, but they do want to know how to create an audit trail and track transactions. A trained writer can pick out the details that are relevant to the audience, and explain them in a "task-oriented" approach that’s suitable to the audience’s needs and interests.
On the other hand, that same accounting program will need internal documentation for use by other programmers in maintaining, troubleshooting, and enhancing the program. Appropriate documentation for this purpose is more likely to be function-oriented: what’s the program doing and how? It still needs to be clearly written, in a logical order, and without leaving out anything relevant to the purpose for which it’s written, because the person using the internal documentation a month or a year from now to maintain the program is likely to be a different person from the one who wrote the program originally.
In this case, the technical writers would need to understand and explain the details of the program at a different level; their background knowledge would need to be more about computing than accounting. The writers’ contribution would be more in organizing the material, ensuring that nothing important is left out, and writing it clearly and unambiguously, rather than interpreting it. Many programmers have decided, after reading poorly written documentation, that they can’t figure out where a problem lies, and that it’s easier and faster to throw away the original program and start again from scratch. I’m sure you’ll agree that’s a major waste of time and money that could have been saved if the program had been properly documented in the first place.
Poor organization
- "But first" – steps not in logical order
- Unclear what’s required and what’s optional
- Unclear who’s doing what: the user? the equipment?
- Lack of retrieval aids: poor or missing index; unclear headings or not enough headings
The most complete and accurate information in the world isn’t going to help you if you can’t find what you need when you need it. I’ve spoken with many installation technicians, struggling with a new piece of equipment, who have to hunt through several thousand pages of poorly organized detail in an attempt to find some critical piece of information. Indexes are frequently inaccurate, incomplete, or non-existent; or they rely on you already knowing some important bit of information, such as what term is used for a particular function or part. If you don’t know what to look for, you’re unlikely to find it.
Poorly organized material can in some cases be dangerous: if readers do the steps out of order, they could damage the equipment or injure themselves. My favorite example of this type of problem is an old M.A.S.H. episode in which they are trying to defuse a bomb that’s landed in the middle of the camp. The instructions are: "Do this. Do this. Do this very carefully. (pause) But first…" just at the point where the previous step could set off the bomb. Your situation is unlikely to be quite this dramatic, but if it means readers have to go back to the beginning and start again, or they’ve just spilled oil all over the floor, at best they’re likely to be quite annoyed.
Other organizational problems include a lack of clarity in who’s doing what: the person who installs the equipment, the person who uses it after it’s installed (not necessarily the same), or the equipment itself. This is usually more of a problem for non-expert audiences, and it arises because an expert writing the material may consider these distinctions too obvious to mention.
A greater problem for a technical audience is the question: is this item or step required or optional? If it’s optional, under what circumstances do I want or need it? What are the consequences if I choose one way or the other? Again, an expert is more likely to assume knowledge or understanding on the readers’ part, or simply never even think of the necessity to explain these issues.
Poor presentation
- Using long, complicated sentences, even if they are grammatically correct
- Using paragraphs when a list, table, or decision tree is clearer
- Lack of consistency
- Ambiguity
Convoluted sentences can be hard to follow. My rule of thumb is: if you have to read it more than once to be sure you understand what’s been said, it needs to be rewritten to make it clearer.
Grammatical problems and complex sentences can also lead to ambiguity; you may think you understand what’s been said, but you get it wrong because it wasn’t clearly presented.
Sentences in paragraphs aren’t always the best way to present technical material. Lists, tables, decision trees and other alternatives may be easier to follow in some circumstances.
Consistency is particularly important when its lack can cause confusion. Don’t vary your words just to make the writing "more interesting" – leave that to novelists. In technical writing, call a widget a widget every time; don’t call it a gadget sometimes or your readers (even technical ones) are likely to wonder if you’re still talking about the same thing. If you’ve got two widgets and need to distinguish between them, find some clear and unambiguous way to do so, and keep in mind that not everyone’s widgets are always the same color.
Factual errors
- Important details left out
- Not kept up to date
What causes these writing problems?
- Writer not familiar with the language, style, and presentation that the audience is comfortable with
- Failure to plan or to allow enough time to do the writing
- "Brain dumping" without restructuring afterwards
- Language difficulties
- Lack of interest or experience
How can a technical writer help you?
I’m assuming that you’ll be dealing with a skilled, experienced technical writer with expertise in writing for the appropriate audience. Such a person can help you in many ways. Here are just a few:
- Planning and management: what documents you need, both external and internal; how best to organize and produce them; time required
- Organization of the material; preparation of templates for your technical experts to fill in
- Writing, rewriting or editing existing material, including different subsets for different audiences
Note: any individual technical writer is unlikely to be an expert in writing for all audiences. For example, proposal writing is a speciality area. You may need to deal with more than one person to adequately cover all your writing needs. In many cases, you won’t want or need a full-time writer, so you’ll find it more cost-effective to bring in a contractor or outsource to a consultant, rather than hiring someone as an employee.
Next month I’ll discuss ways to locate writers and how to find the perfect match with your needs.
Jean Hollis Weber is a technical writing consultant with over 20 years of experience writing and editing scientific and technical materials, most recently in computing and high-tech industries. Originally from the USA, Jean is now based in Australia. She teaches short courses in technical editing and lectures at several Sydney area universities. She is now specializing in online materials, including Windows help and Web publications.
Last updated 28 December 1998