Tags
No tags :(
There’s no reason why technical writing shouldn’t be lively and interesting. The real challenge is to express complex ideas simply. Too often technical writing has a flat style making documents difficult and tedious to read. As in all good writing, you should put across your message in clear English and avoid complex words, acronyms, jargon and passive verbs. You should also keep your average sentence length low. The real challenge in technical writing is to express complex ideas simply. Click the link below and follow my guidelines to help improve your reports.
Understand the type of technical report you are writing.
Technical reports come in all shapes and sizes, but they all share the same goal of communicating information clearly. Deciding what type of document you need to write is an important first step as it influences your approach.
For example, the following demand different approaches.
Reporting Research Findings
These documents describe the work done to gather information in the laboratory or field. They can be simple recording or data or more thorough and include: the problem or issue examined, the method or equipment used, the data collected and the implications.
Simple Technical Information Report
This document explains a technical subject. It has no aim other than to make sure readers understand the topic clearly. For example, a technical report on a investing in the futures market would probably explain how the market evolved, how it works, the specialist terms used and so on. A simple technical report for information does not put forward a view on the merits of investing in the market or have recommendations.
Technical Specifications
Specifications typically consist of descriptions of the features, materials, uses and workings of new product. Good specifications concentrate on graphics, data and illustrations rather than written descriptions. Think of a patent application as a good example.
Technical Evaluation Reports
Evaluation reports, sometimes called feasibility reports, present technical information in a practical and logical way to decide whether something is possible. For example, a technical evaluation report into setting up an intranet site for a corporation would examine if this was possible, set out the steps needed and point out any problems. It does not recommend if the corporation should set up its own intranet site.
Technical Recommendation Reports
These reports lead to specific recommendations. It builds on the evaluation report and comes to specific recommendations to help the decision-maker adopt the best solution. Of course, some reports often have both the evaluation and recommendation reports rolled into one
Technical Manuals and Instructions
Here the emphasis is on using appliances, equipment or programs. The task here is to write step-by-step procedures anyone can understand and follow.
Write down your specific aim
Ask yourself ‘why am I writing’ and ‘what am I trying to achieve?’ If you don’t know, the chances of writing good technical specifications are remote. If you define your aim, you can then evaluate all information, arguments and recommendations against that aim. For example, you might be writing a report on Firewall Software, but your aim is different if you need to write a one-page summary or a 100-page technical specification.
If you define your aim as:
Aim: Explaining how firewall software protects the company’s data.
With this aim at the forefront of your mind, you can decide on the most relevant information. You might decide to:
- Exclude alternatives to firewall software.
- Exclude a review of different firewall software packages.
- Stress the specific company information most at risk.
- Look at the cost of introducing the software compared to the cost of losing data.
- Describe the worst-case outcome.
- Examine the technical issues to overcome in using firewall software.
Setting down your aim must be the first step in any piece of writing. By focusing your thoughts, you have started to think clearly about what your readers need to know.
When working out your aim, you may need to clarify the task by asking your supervisor or colleagues questions about the task. Keep asking questions until you have a clear idea of why you are writing and what you want to achieve as it will help collect the right information and decide how to present it to your readers.
If you have more than one aim, sort them into priority order.
Plan the sections and subsections you need
With technical writing you must present your information so readers can:
- use the report for the purpose for which it was requested;
- extract the main points without necessarily reading the whole;
- easily find the information that interests them;
- and quickly absorb the crucial information they need to know.
If you don’t organize your document well, readers may miss important information. It is up to you to present your information in a readable and well-organized way. You should offer informative summaries, clear instructions and a logical arrangement to let your readers pick and choose the parts they want to read.
For example, think of a good Internet page. Isn’t it easy to navigate and get the information you want quickly? As readers will not read from the opening page to the last page, good organization here is essential. This is just as true of a manual where readers need to find out how to fix a problem or a report where the reader wants to find the reason for a technical decision.
So it’s a good idea to write down the sections and subsections you need to plan your document. This helps you think about your aim and your readers’ needs, drop unnecessary information, stress important information and so on
Avoid starting with Background, Introduction or Methodology.
These headings encourage you to warm up to the writing task and waste the most valuable part of the document—the first page. Instead, use the opening page to present the essential information. For example:
CONVENTIONAL OPENING:
Report into Firewall Software
Background
The IT Assessment Group has drawn this report together to examine the alternative ways of protecting the company’s data. In particular, the concept of firewall software, defined as software that can be used to protect an organization from viruses and unauthorized entry into databases) and its use within the organization is assessed. In order to assess the alternatives available, six independent technical evaluators were briefed on the company’s databases, existing procedures. This report draws on the conclusions of the six evaluators.
ESSENTIAL INFORMATION:
Report into Firewall Software
Firewall Software
Protecting the Company’s Data
Firewall software is essential to protect the company’s databases from viruses or unauthorized access. By investing $20,000 in the latest software, the company will safeguard its 30,000 customer records and accounts and protect itself against credit-card fraud — estimated to cost the industry $2.5 billion a year.
Once you have written down your sections and subsections, review them. Drop ones that are not essential. Then work out the best order to let readers pick out the information they need.
Write your headings using strong verbs and specific nouns
When you have your sections and subsections, give them headings with strong, active verbs and specific nouns. Pay particular attention to adding strong verbs to your headings. This transforms the look and feel of the document and will encourage you to write in a more direct and interesting style. For example:
Standard Headings
1. Present Method
2. Need for Change
3. Proposed Method
4. Warehouse
5. Factory
6. Shipping Depot
7. Office
8. Cost Comparisons
9. Recommendation
Headings with Strong Verbs and Specific Nouns
1. How the Assembly Line Works
2. Adopting a Mechanized Assembly Line
3. Choosing the Just-in-Time Principle
4. Warehouse — Keeping Enough Stock
5. Factory — Updating the Assembly Link
6. Shipping Depot — Meeting Order Deadlines
7. Office — Checking the Paperwork Saving
8. Costs and Improved Turnaround Times
9. Adopting a Mechnized Auto Assembly
Headings help keep you organized and focused on the topic. They break down information into shorter, easier-to-handle items and keep you close to your original aim and your readers’ needs.
Match your content to your readers’ knowledge.
As always, your readers are all-important. Writing for the public or writing for specialists will alter how much technical information you can include.
If you are in doubt, aim for the simpler approach. It’s much better to take a little longer to explain something so everyone can understand than to use jargon that’s a short-cut which alienates or confuses some of your readers.
However, you still have to draw a line somewhere. For example, you may have to write for both technical and nontechnical readers. Suppose you have to explain how the cooling mechanism in a warehouse works. You may have to assume the expert and the nonexpert audiences both understand common terms such as ring seal, stop value, thermostat. But you may need to explain more complex terms, such as coolant temperature matrix, even if expert readers know the terms.
Poor Technical Writing
The 15ATS series toggle switches, in excess of 200 in total, were subject to the extreme of temperatures caused by being in close proximity to the furnace. This in turn caused heat failure as the expansion of metal caused a fault whereby the metal connection fused. The heat of the furnace has to be over 600 degrees Fahrenheit before this effect takes place.
Concise and Easy to Read
Over 200 automatic toggle switches fused when the keypad melted as the furnace temperature rose to over 600 degrees Fahrenheit.
Remember, readers can usually handle a few specialist words or terms if the writing style is concise and easy to read.
Keep information specific rather than general.
Have you seen readers going through documents, using a highlight pen to find the key words, facts and figures. They do not highlight phrases such as: As you will be aware, the purpose of this document is to… in the order of… Readers want to take specific information from technical documents. For example:
General
heavy precipitation during the period
excessive heat
select the appropriate key
Specific
four inches of rain in 48 hours
120 degrees Fahrenheit
click Alt-B
As long as you guard against going into excessive detail, replacing general information with specific information will improve your technical documents. For example, if a manager want to know why production stopped for an hour on the assembly line, the author has to decide just how specific to make the message.
Too General
Problems arose in a number of areas of the stock transportation device that required intervention by an appropriately qualified member of staff so remedial action could be taken.
Specific
As the temperature rose to 120 degrees Fahrenheit, the coolant for the metal rollers overheated causing the conveyor belt to jam. To keep the belt working, a mechanical engineer had to reset the timer and rollers on the conveyor belt, replace the coolant and slow the belt by 25% to 200 feet an hour.
Excessive Detail
Monitoring the temperature saw a rise from 80.5 degrees Fahrenheit to 124.5 degrees Fahrenheit causing problems in the coolant’s temperature. As the coolant’s optimum operating temperature is 80 degrees Fahrenheit, the result was an expansion of the coolant beyond its maximum operating temperature level of 105 degrees Fahrenheit. This in turn led to a failure of the conveyor belt that was rectified by the mechanical engineer assessing the exact cooling coefficients needed with a possible ambient temperature above the manufacturer’s recommended levels.
Three reduced settings were considered, namely reducing the belt speed by 10%, 20% and 25%. These would lead to a reduction in the in-line assembly velocity of 80 feet, 160 feet and 200 feet an hour respectively.
The optimum setting was 25.32% of the previous 800 feet an hour rate. However, before this was set, the engineer had to replace the 3.5 gallons of coolant used and reset 42 or the 360 rollers on the belt.
Just how specific your writing should be depends on the reader and your reason for writing. If our example, if you were trying to identify the reason for the belt stopping for a technical manager who needs to act to stop the fault reoccurring, you would need to go into technical details of the specific failure. If you are writing for nontechnical manager who wants to know why there’s a problem and how you fixed it, the specific information shown is enough.
Choosing how specific your information should be is a constant problem for the technical writer. Remember, you’re trying to pitch the information exactly for the needs of the reader. Aim to write and describe concrete information without straying into irrelevant information.
Write in plain English
Good writing, whether technical or general, presents relevant information in a clear style. Technical writing has such a poor reputation—ask users what they think of computer manuals—because writers fail to use the clear, plain English style.
Plain English is a simple style that anyone can understand. You have to control sentence length, use active verbs, cut down on unnecessary jargon, make your writing specific and tight. This is not the way we learn to write at college or in the workplace. The culture of academic writing and business and scientific writing is the dull, long-winded, passive style. Take the following example; then compare the draft in plain English.
Original
From any page of a site, links can be found which point to other pages in the same site or to other sites, wherever they may be. Specifically, these links are addresses which are called URLs. However, what is interesting for the visitor is not the address itself, but what can be found there, and so generally the address is not displayed. Instead, what you find there is highlighted in the text (by underlining it and displaying it in another color, often blue).
Redraft in Plain English
You can link any page to other pages on the same site or different sites. These URL addresses, usually hidden from view, guide the user to the right page. The user can then click on any underlined text, often shown in blue, and more information pops up.
Only a small percent of technical documents are in plain English. These are often drafted by the top-flight, professional writers, usually with journalistic or editing training and experience. Almost every technical writer needs help breaking poor style habits. The quickest way to learn to write in plain English is to use the StyleWriter editing software. I developed this program to find the plain English problems in your writing. StyleWriter highlights them in your technical report and explains how to edit them. Many of our users are technical writers and they highly recommend it.
Use active verbs rather than passive verbs
Using active verbs is the first rule of good writing. All authorities on good writing, including scientific and technical bodies, recommend active verbs rather than passive verbs. Why? Passive verbs are longwinded, ambiguous and dull. Active verbs make your writing simpler, less awkward, clearer and more precise. Here’s an example:
Passive Verbs
The QMS Magicolor 2 Printer is equipped with two interfaces, one is known as the parallel interface, the other is known as the Ethernet interface. Whatever interface connection is needed, you will find that MS Windows 98 has already been preinstalled and your software applications are based on this platform.
(50 words)
Active Verbs
The QMS Magicolor 2 Printer has Parallel and Ethernet interfaces. Whatever interface you need, you will find your software applications will work on the preinstalled MS Windows 98.
(28 words)
Technical writing is full of passive verbs because most people learn to in the third person because it is supposedly more objective. This is a false notion. In the next example, the passive and active are both objective—but the active sentences sounds more natural and are 29 words shorter.
Passive Verbs
The experiment was conducted so that the relationship between the two theories could be examined. First, the cultures were prepared and then were examined under the microscope to see if any impurities could be found. Once the purity of the samples could be established, they were used in six independent tests.
(51 words)
Active Verbs
The experiment examined the relationship between the two theories. First, microscopic examination for impurities isolated pure examples used in six independent tests.
(22 words)
In switching your style from passive verbs to active verbs throughout your writing, you face several problems:
- You must accurately spot them. Often writers miss passive verbs or try to change verbs that are already active.
- You need to measure your use of passive verbs. One or two passive verbs a page will not ruin your style, nine or ten will.
- You need to know how to turn passive verbs to active verbs.
Keep your average sentence between 10 to 20 words
Long sentences make any document hard to read. In technical documents keep your average sentence between 10 to 20. You may go down as low as 10 or 11 words if you’re writing instructions with many short, sharp sentences telling the user what to do. However, if you get below 10 words, you’re probably overdoing the technique of short sentences.
Compare these examples:
Long Sentence
A highlight of the web site is the development of two types of electronic advisory systems—Expert and Technical where both of the systems inform the user about standards by either asking a series of questions which determine whether, how, and which specific parts of the standard apply to the user’s activities, or addressing complex standards by placing in one location a large amount of information about the standard.
(One Sentence—70 words)
Shorter Sentences
The web site offers both expert and technical advice sections. These explain standards by asking questions to find out if and how the standards apply to the user. They also address complex standards by placing all the relevant information in one place.
(Three sentences—Total 42 words)
Sometimes, it helps if you break long sentences into a list.
Long Sentence
Physical inventory records can be accurately kept for exchange transactions by reduction of the inventory from the receiving report and requiring customer services to prepare a production report on repaired items going back into the inventory as a replacement for items that have been sent to the customer in exchange.
(One Sentence—50 words)
Shorter Sentences
To keep inventory records accurately for exchange transactions:
Reduce the inventory from the receiving report.
Ask customer services to prepare a production report on repaired items and list the replaced items sent to the customer on the inventory.
(Three sentences—Total 40 words)
Edit wordy phrases
Padding is the enemy of good writing. Unnecessary words and phrases clutter up sentences and obscure meaning. By comparison, economy of words is the mark of good writing. You have to learn to make every word count in technical documents. You must edit ruthlessly, cutting any word. Set yourself a target of cutting 10 to 20 percent of the words in your document.
Wordy
To understand and interpret an applet, the browser must have a Java virtual machine at its disposal. This is the case, in particular with Netscape Navigator and Internet Explorer, as well as Sun’s HotJava. However, we have already mentioned several times that many Web surfers are attached to older browsers with which they feel comfortable. This being the case, if you use Java you will limit the number of visitors who will be able to wonder at what your applets do. In addition, browsers have a configuration option which allows (for security reasons, for example) the Java virtual machine to be turned off. Cautious people make frequent use of this option.
(111 words)
Concise
Browsers such as Netscape Navigator, Internet Explorer and Sun’s HotJava can only use applets with Java virtual machines. If Web surfers use older browsers, which do not understand Java, or switch the Java option off for security reasons, you will have fewer visitors to your site.
(46 words)
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.
Complex Words
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.
Simple Words
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
- non-words
- 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.
Jargon-ridden
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.
Jargon-free
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:
Profession Example
Computers batch processing, JPEG and macros
Law affidavit, easement and surety
Mathematics duodecimal, rhomboid and standard deviation
Medicine 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?
CRA Camera-ready Artwork
DPI Dots Per Inch
DTP Desktop Publishing
PMS Paint Matching System
UGD 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 (i.e. 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 KS
- 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.
Avoid non-words
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:
activities, amenities, amenity, aspects, concepts, devices, elements, facilities, factors, functions, inputs, operations, outputs, processes, resources, sectors, structures, systems, variables
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.
Keep technical terms to a minimum.
Although a specialist technical vocabulary is necessary, don’t let this be an excuse to use the technical word unthinkingly. For example, in a desktop publishing manual you could use the terms folio, recto and verso. But why? The simpler page or page number (folio), right-hand page (recto) and left-hand page (verso) are easier for the reader to follow.
Use examples and illustrations.
When you write up your technical information, remember to use examples, illustrations and analogies to explain difficult information or new ideas. For example:
The operating system of your computer is like the bridge a ship, the control center for everything that happens on your machine.
A simple example or illustration can go a long way to making technical writing understandable.
Use diagrams, flowcharts and graphs.
The cliché a picture is worth a thousand words is true. A good diagram, flowchart or graph can present information quickly that would take ten sentences to explain. Click here to see a diagram showing the a car’s clutch. Such a diagram makes any explanation or technical description far easier to understand.
Use good layout to draw attention to key technical information.
Good layout can help guide readers to key information. For example, when writing instructions you want the reader to take in numbered bold statements.
Test your document with the intended readers.
For many technical documents you need to test them on the intended readers. Show users instructions and get them to carry them out. Rework any area where users slowed down. Rethink, redesign and rewrite any area that confused users. Make sure all users can go from the start of each instruction to the end without faltering.
Such testing on readers will show up ways to improve documents that even the best technical writers would have missed.
