Summary: People turn to technical documents because they need help with a specific problem. Write clearly and plainly. Preview your document on real people, to see whether they can actually use it. The needs of your primary readers may differ from your own needs or those of your boss.

Technical communication aims for clear, jargon-free language.  Only the dishonest and the incompetent benefit from deliberately hiding the truth behind a fog of jargon. (For more on the benefits of clear writing, see the U.S. Government’s Plain Language Action Network.)

Poets, politicians, and marketers regularly aim to evoke emotional responses, and thus have a much freer reign.  Nevertheless, the responsible use of emotional language does have a place in technical writing.

Put yourself in your reader’s place. Even if all your research is accurate and your equations are correct, your hard work is wasted if your reader can’t understand you, or isn’t convinced your conclusions are accurate.

• Who is going to read your report, and why?  Don’t produce words simply for the sake of trotting out everything you ever learned about the subject. A real human being will read your report, hoping that it will help him or her solve a particular problem. Organize your document for the convenience of that reader (whose goals and expectations are probably not the same as yours).
• How can you help your reader solve a problem? By giving them the information they need, quickly and efficiently.  Put the most important information in the very first sentence, if possible. Then, touch on all the major points — in a single sentence, if possible — and show how these main points are supposed to fit together.  Then, you can follow up with as many details as your reader needs.  (A good abstract helps a reader make sense of the details that will follow.)
• How do you know what your readers really need?  By watching them. Give a rough draft to a volunteer who knows little or nothing about the subject. Don’t just ask, “Do you like it?” or “Do you think it’s clear?”  Run a little experiment. With your mouth shut, pay close attention to which passages your reader stumbles over, misunderstands or skips entirely. If you’re not happy with the result, revise and try again. (See: “Usability Testing: What is it?“)

Consider the following two abstracts, reproduced from the Annals of Improbable Research(a satirical publication that pokes fun at inflated scientific language).

Every discipline its own good reasons for developing specialized language. For instance, in geometry, a “toroid” is a shape resembling a donut.  Depending on their purposes, technical documents may be intended for readers who don’t know the subject as well as the writer does; a term that seems familiar to you is likely to confuse at least some of your readers.

Does this mean that all technical writing should be dry, “See Spot run” sentences?  Of course not.

Complex issues will naturally require advanced vocabulary and complex sentences, but the reader never benefits from needless complexity. Many documents that seem impenetrable to beginners would be much more readable if they included a background section, which gave the past history of the project, defined any unfamiliar terms, and briefly described the issues that led up to the creation of the report.

Humor, human interest, and vivid examples can make a dry report more accessible. If you think such details would bore experts who might read your report, just tell the experts what page they should skip to, or consider putting all the welcoming, friendly stuff in a supporting “Let’s Get Started!” document.

Avoid Emotional Jargon, Too

Technical documents should generally avoid emotionally-laden buzzwords. While the persuasive force of emotions makes them far too powerful to ignore in any human transaction, an ethical technical communicator would not use emotion as a substitute for factual evidence.

Emotion satisfies leisure readers, but often frustrates technical readers. People who pick up a historical biography or a literary book review are fully intending to spend a chunk of their leisure time with the text; they will keep reading as long as the emotional or aesthetic payback is worth the effort. In order to hold the attention of the reader, a short story or essay builds tension by creating expectations, dropping hints of coming events (foreshadowing), incrementally raising the stakes, and so forth.

• If you write an essay about the most stressful job interview you ever had, you might save an important detail — whether you got the job — for the end, where it will have a bigger impact. The value of that essay would be the emotional effect it has on the reader, who may empathize with your plight, or laugh at it (depending you the tone your story takes).
• If you write a formal report alleging unfair hiring practices at a particular company, and use your personal experiences in order to raise funds to pursue a lawsuit, you would approach the subject differently. In this case, the goal is not simply to tell the story, but to get your reader to make a financial decision to support your legal action.

Emotional jargon is imprecise. What, in technical terms, do words like “humongous” or “very cute” mean?  Give the object’s dimensions, if you can.  Since there’s no standard way to measure a subjective term like an object’s “cuteness”, you would have to conduct a little experiment.  You might show 10 different pictures to 100 college students, and have them respond to the statement, “This picture is cute,” with -3 being “I strongly disagree” and +3 being “I strongly agree.” That doesn’t actually give us a scientific definition of cuteness, it just records what these 100 college students did when asked to rate the cuteness of some pictures, so any report that uses those results should be clear about what, exactly, the results mean.

Emotional jargon is powerful. Emotion can be a powerful persuasive force, and is thus useful in many professional communication situations.  For example, a factory’s health and safety manual might list the names of all employees killed or injured on the job; a brochure about sexual assault may include a few story-like examples that describe risky behavior on college campuses.  In such cases, the emotional effect of these passages reinforces and amplifies the factual document.

Next: Begin With Your Conclusion

Dennis G. Jerz
25 Oct 2001 — rough draft first posted
10 Nov 2001 — last modified
23 Aug 2012 — minor updates 

Technical Writing > Short Reports [ 1 | 2 | 3 ]