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.
Consider the following two abstracts, reproduced from the Annals of Improbable Research(a satirical publication that pokes fun at inflated scientific language).
| Pompous and Wordy (“Scientific”) Version | Clear Revision |
| “How to Write a Scientific Research Report” The stacking properties of toroids that reflect radiation in the 1.8 to 2.8 eV energy range is investigated. Preliminary results indicate that in the optimal configuration the toroids are oriented vertically with those reflecting lower energy photons having larger gravitational potential energies for toroids of equal mass. The ambiguousness of this solution is tested by experiments performed by a relatively inexperienced researcher (t= 0.9167 yr). These experiments indicate that alternate solutions can be found. | How to Write a Clear Research Report We had some fun with a stacking rings toy and learned something about how the perceptions of adults are different from those of babies. [While adult researchers always stacked the smaller toy rings on top of the larger ones, a baby never stacked the rings the same way twice. Who can say which solution is ‘correct’?][I added the bracketed portion myself, in order to make the abstract more informative. –DGJ] |
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.
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.
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 ]
| Writing Short Technical Reports |
| Begin with Your Conclusions A technical document is not a mystery novel. Don’t save your best points for the end, because most readers are too impatient to wait.Use Appropriate Section Headings For any document longer than a page, break up the content into subsections like introduction, background, discussion, and conclusion. |
View Comments