Technical Writing and Writing a Technical Report

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 stepby-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 dont 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 companys 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 dont 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. Isnt 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 its 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 documentthe 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 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 The Mechanization of Auto Assembly 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 Mechanizing Auto Assembly 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. Its much better to take a little longer to explain something so everyone can understand than to use jargon thats 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 Concise and Easy to Read

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.

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 Specific

heavy precipitation during the period excessive heat select the appropriate key

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 coolants temperature. As the coolants 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 manufacturers 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 theres 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, youre 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 reputationask users what they think of computer manualsbecause 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 Redraft in Plain English

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).

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. This program finds the plain English

problems in your writing, highlights them in your technical report and explains how to edit them. I use StyleWriter for all my reports and 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 Active 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)

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 objectivebut the active sentences sounds more natural and are 29 words shorter. Passive Verbs Active 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)

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 Shorter Sentences

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 Sentence70 words)

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 sentencesTotal 42 words)

Sometimes, it helps if you break long sentences into a list. Long Sentence Shorter Sentences

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

To keep inventory records accurately for exchange transactions: 1. Reduce the inventory from the receiving

back into the inventory as a replacement for items that have been sent to the customer in exchange. (One Sentence50 words)

report. 2. Ask customer services to prepare a production report on repaired items and list the replaced items sent to the customer on the inventory. (Three sentencesTotal 40 words)

Keep technical terms to a minimum. Although a specialist technical vocabulary is necessary, dont 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.

Information drawn from: http://www.technical-writing-course.com/type-of-technical-report.html