Monday, August 01, 2011 - Page 5 of 6
How to write a technical report
Use simple words rather than complex ones.
Many writers have difficulty keeping their message simple and clear. Instead of using everyday words they use complex or unfamiliar words. Simple, everyday words will help you get your message across. Too often technical writers use words such as additional, indicate, initiate and proliferate instead of the simpler extra, show, start and spread.
As we noted in the preceding section, if you purchased additional printer options, such as a second printer tray, it is a requirement you verify its correct installation.
As we noted in the previous section, if you bought extra printer equipment, such as a second printer tray, you must check that you installed it correctly.
Avoid jargon, especially:
- acronyms and abbreviations
- abstract words and phrases
Readers hate jargon—and technical writers have a poor reputation for jargon. It's the most cited problem in technical documents and one you have to be on constant guard against.
Most refractory coatings to date exhibit a lack of reliability when subject to the impingement of entrained particulate matter in the propellant stream under extended firing durations.
The exhaust gas eventually chews the coating of existing ceramics.
More than any other writing problem, jargon depends on your audience. Write a manual for Visual Basic for existing users of the language and your technical jargon is a short-cut to information. The same technical jargon to someone learning Visual Basic makes understanding the subject more difficult. To those with no experience of Visual Basic the technical jargon becomes an impenetrable forest of abstract or unknown terms.
However, jargon is more than a specialist term. For example:
|| batch processing, JPEG and macros
||affidavit, easement and surety
|| duodecimal, rhomboid and standard deviation
||angina, cerebral palsy and tonsillectomy
Each of these professions needs these specialist terms. They specifically describe something, even if the word is not in the average person's vocabulary. Many of the words are in a good dictionary and all are in your spelling checker. So use such terms freely, offering explanations if you expect your readers to have problems understanding. For example, a doctor might explain the need for a tonsillectomy to a patient by saying, ‘You'll need to go into hospital for an overnight operation to remove your tonsils.’ But to use such an explanation in a report to his or her peers would be unnecessary.
Avoid acronyms and abbreviations
The most common and irritating form of jargon is overuse of acronyms and abbreviations. Ask readers what they dislike about any technical writing and they'll say jargon. Ask them to give you an example and they'll say: 'All those abbreviations.' Here are some abbreviations from a computer manual. How many do you know?
||Paint Matching System
||User Guide Documentation
How many did you get right. Two out of six? Probably DPI for dots per inch and DTP for desktop publishing as these are industry terms. Many people would not have recognized these two. As for CRA, camera-ready artwork would be better. SC for spot color is an unnecessary shortened form and UGD for User Guide Documentation is longwinded for the word manual.
Here are the rules to keep acronyms and abbreviations under control.
- Use the abbreviation without explanation, if everyone knows it.
IBM, USA, Washington DC, BMW, PhD
- Note: avoid using an abbreviation if it's commonly understood as one term and you mean another. For example, do not use PC for politically correct or for Privy Council as most people think of it as meaning personal computer.
- Use the ten to twenty most common and understood acronyms in your organization without explanation when writing internally. Prefer the full form and the shortened word form when writing to other audiences and especially if writing to the public.
- Use the shortened word form to avoid most abbreviations.
Kennedy Space Center becomes Center—not KSC
- Use common sense. If the abbreviation is better in the shortened form and causes no problems for any of your readers, use it freely. For example, if you are writing a leaflet about Personal Equity Plans and the word Plans could either confuse or become tedious, it might be better to use the shortened form PEP.
- Limit your use of shortened forms to one or two in any document, no matter what its length.
- The abbreviations to avoid are the one's you think it is necessary to explain in brackets the first time you use them. Each time you do this you set a memory test for your reader. We have tested this by asking ten managers to read a two-page memo with two abbreviations explained on the first page. When they turned the page and read the abbreviations, we asked them what they stood for. Only one person correctly stated what one stood for—a 95% failure rate.
- Use your spelling checker to find acronyms and abbreviations—it's a constant reminder you may be overusing them. If you want to find the ones used in your organization, look at the added dictionaries on your word processor.
- Remember that using abbreviations and acronyms can go dreadfully wrong in the reader's mind. In the United Kingdom, there's an acronym in common use called PMT for pre-menstrual tension—the United States equivalent is pre-menstrual syndrome. One engineer once wrote to a woman customer stating—“I intend to come and inspect your PMT next month.” He was referring to a Pole-Mounted Transformer.
Try to avoid words that do not exist when you write. If your spell-checker highlights a word such as autoized, groupware or helpware in your document, the chances are you're straying into the world of the jargon writer. Keep to words people understand or at least can look up in a standard dictionary—your readers will thank you for the effort.
Avoid abstract words and phrases
One habit you should avoid, common to most technical writers, is overusing abstract words. Here's a list of the most common ones to avoid in your writing.
|Abstract words to avoid in technical writing
For example, what is a device, output or facility. Such words are so abstract they become meaningless to the reader. String them together, such as output device and you have instant jargon for the word printer. Add them to acronyms and you can produce CAS Facility which in turn means Civic Amenity Site Facility, pure jargon for Council Recycling Site.
||page 5 of 6