Effective Technical Writing6e21898d22ccea8d172c-9c864806c5e4c14e9b6f9c418f488ed3.r59.cf1.rackcdn.com/... · L1.4 Effective Technical Writing 7. Meeting Report Opening – Purpose–What

© American Management Association. All rights reserved.

Effective Technical Writing

Lesson Worksheets

2216V • Updated 02/2011

© American Management Association. All rights reserved. i


Table of ContentsLesson One

Technical Writing–The Maps ...........................................................................................................L1.1Most Important Points ....................................................................................................................L1.6

Lesson Two

Assignment 2.2: Drafting–Theory and Practice .............................................................................L2.1

Lesson Three

Assignment 3.1: Highlighting the Main Point ...............................................................................L3.1Transition Words and Phrases .........................................................................................................L3.2Basic Qualities of Effective Illustrations .........................................................................................L3.3

Lesson Four

Resources .........................................................................................................................................L4.1Reading List ...................................................................................................................................L4.13

LESSON 1

© American Management Association. All rights reserved. L1.1


L1.1

Technical Writing–The Maps

The Faces of Technical WritingTechnical writing is unique in both the highly specialized nature of the content and its need to convey objectivity. Along with writing e-mail, memos, and letters, the technical writer must often prepare defi nitions, physical descriptions, product specifi cations, narratives, procedures, test and lab results, audit reports, project and program evaluative reports, trip reports, research studies, root cause analyses, and proposals.

The following content and format guidelines are not the only approach to writing the types documents they describe; however, they make for an excellent starting point for the technical writer looking to jumpstart the writing process on a challenging assignment.

1. Root Cause/Investigative Report

Opening

– Problem–What happened? – History–What is the history of the problem? – Effects–How did the problem affect the business?

Discussion

– Methods–What procedures were employed to investigate and correct the problem? – Causes–Why did the problem occur? – Solutions–How was the problem corrected?

Closing

– Short-Term Recommendations–What can be done to avoid an immediate recurrence? – Long-Term Recommendations–What can be done to mitigate the problem permanently?

2. Evaluative/Feasibility Report

Opening

– Purpose–What are the subject and purpose of the evaluation? – Nature–Is this a planned, progress, or completion report? – Authorization–Which person, group, or law requested or required the evaluation? – Impact–Why is the evaluation signifi cant to the business? – Scope–What areas of the subject did the evaluation include, and what areas of the subject

did the evaluation exclude? – Limitations–What restrictions, if any, prevented a more thorough evaluation? – Standards–What criteria were used in evaluating the subject?

Discussion

– Findings–What did the evaluation reveal about the subject in each area of the scope? – Accomplishments–What direct or indirect achievements were realized? – Problems–What direct or indirect setbacks were encountered? – Validity–Are the fi ndings valid? (Do the fi ndings emerge from the observations?) – Reliability–Are the fi ndings reliable? (Are the results repeatable if reviewed again?)

LESSON 1



L1.2

Closing

– Conclusion–What are the key fi ndings and their impact on the business? – Recommendations–What action steps can be taken based on the fi ndings? – Lessons–What are the lessons learned at this point of the reporting process?

3. Historical/Status Report

Opening

– Purpose–What is the topic of the report? – Authorization–Which person, group, or law requested or required the report? – Period–What is the period covered in the report? – History–What important issues led to the need for the report?

Discussion

– Status–How is the situation as it now stands? – Standards–On what measures is the status being assessed? – Impact–What is the importance of each point discussed? – Methodology–What processes or procedures were performed?

Closing

– Goals–What are the next steps, and who will complete them before the next report? – Timeline–What is the schedule for the tasks to be completed?

4. Process/Procedural Report

Opening

– Purpose–Why is the process or procedure necessary? – Goals–What should the completed process or procedure achieve? – Defi nitions–What technical terms, principles, theories, or concepts need clarifi cation? – Materials–What materials, equipment, ingredients, or components are necessary? – User–Who is an authorized user, and what are the credentials required to complete the

procedure? – Precautions–What safety actions must be performed before and during the procedure?

Discussion

– Setup–What preliminary actions need to be taken before the procedure can begin? – Procedure–What are the chronological steps needed to complete the process or procedure? – Illustrations–What illustrations would help the user complete the procedure effi ciently?

Closing

– Results–What should be the state of the fi nished process or procedure? – Troubleshooting–What human, electronic, or documented resource can be consulted if

problems occur during the procedure?

LESSON 1



L1.3

5. Trip Report

Opening

– Purpose–What is the purpose of the trip? – Authorization–Which person, group, or law requested or required the trip? – History–What important issues preceded the need for the trip? – Scope–What topics are covered in the discussion of the report? – Methodology–What processes or procedures were performed?

Discussion

– Reviews–What reviews were completed (e.g., consultative meetings, facility tours, management interviews, document examinations)?

– Limitations–What issues were encountered to prevent a more timely or thorough report? – Recovery–What plan is in place to compensate for the noted limitations?

Closing

– Conclusions–What is the status of the topic of review? – Recommendations–What recommendations are needed based on the review?

6. Audit Report

Opening

– Purpose–What is the purpose of the audit? – Authorization–Which person, group, or law requested or required the audit? – Auditee–What organization, group, or process was the subject of the audit? – Scope–What elements were audited? – Methodology–What processes or procedures were performed? – Summary–What were the key fi ndings, impacts, and recommendations?

Discussion

– Finding–What effi ciency or defi ciency was found? – Standard–By what measure is the audit point being measured? – Observation–What specifi cally did the audit reveal? – Impact–How do the fi ndings affect the business, process, or stakeholder? – Cause–Why is the defi ciency occurring? – Conclusion–How do the fi ndings relate to the auditee’s or the stakeholder’s wellbeing? – Recommendation–What corrective action should be taken? – Benefi t–How will the auditee profi t from correcting the defi ciencies?

Closing

– Response–What has the auditee committed to rectifying in the audit? – Follow-up–When will the next audit on the defi ciencies take place?

LESSON 1



L1.4

7. Meeting Report

Opening

– Purpose–What was the purpose of the meeting? – Attendees–Who was present at the meeting?

Discussion

– Issue–What were the topic and impact discussed? – Action–What measures will be taken to address the issue? – Timeline–When will the action items be completed? – Owner–Who is responsible for the action item?

Closing

– Disclaimer–Who shall be contacted to correct any misstatements in the meeting report? – Follow-up–When will the next meeting take place?

8. Lab/Experiment/Test Report

Opening

– Purpose–What was the purpose of the experiment or test? – History–What events led to the need for the experiment? – Goal–What is the expectation of the experiment? – Signifi cance–Why is the goal important to the business, condition, or stakeholders? – Methodology–How was the experiment or test conducted? – Materials–What materials and equipment were used?

Discussion

– Results–What results did the experiment reveal? – Contingencies–What unexpected events occurred during the experiment or test? – Controls–How did the researchers compensate for the contingencies? – Validity–Are the fi ndings valid? (Do the fi ndings emerge from the observations?) – Reliability–Are the fi ndings reliable? (Are the results repeatable if reviewed again?) – Analysis–How do the results affect the business, condition, or stakeholders?

Closing

– Conclusions–What, in summary, are the signifi cant inferences and predictions to be drawn from the results?

– Recommendations–What next steps can be taken for future testing?

LESSON 1



L1.5

9. Justifi cation/Proposal

Opening

– Recommendation–What or who is needed? – Benefi ts–Why are they needed? – Authorization–Which person, group, or law requested or required the proposal? – Problem–What issue does the proposal address? – Standard–What situation should be the case? – Status–What situation is the case? – History–What events led to the status? – Causes–What contributing factors affect the issue? – Impact–What business issue or function is at stake because of the status?

Discussion

– Methodology–How has the problem been investigated? – Options–What choices are available to correct the problem? – Factors–How are the options being measured (e.g., endorsements, experience, accuracy,

speed, capabilities, usability, training, durability, cost, warranty)? – Solution–What is the best option? – Rationale–Why is the solution the best option?

Closing

– Conclusions–How is the problem addressed by the suggested solution? – Recommendations–What are the next steps (e.g., pilot program, outright purchase)?

LESSON 1



L1.6

Most Important PointsIn the space below, list any points that you learned or practiced in the workshop and want to commit to memory and further practice.

Lesson One

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

Lesson Two

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

Lesson Three

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

Lesson Four

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

__________________________________________________________________________________________

LESSON 2



Assignment 2.2: Drafting–Theory and PracticeDirections: List some of the problems of rewriting prematurely and the benefi ts of drafting nonstop in the table below.

Drafting: Theory and Practice

Problems of Rewriting Prematurely Benefi ts of Drafting Nonstop

LESSON 3



Assignment 3.1: Highlighting the Main PointDirections: Choose one of the three versions of the same message that best highlights the main point.

1. Our main network of computer equipment will be offl ine for installation of new equipment from June 3 to 15. During this period, computer operations will be conducted in Room 108. We are also scheduled to train fi ve new employees at this time. Room 108 is too small to accommodate computer operators, trainers, and trainees. Therefore, we request that you delay sending us the trainees until after June 15.

2. We request that you delay sending us trainees to operate computer equipment until after June 15.

Our main network of computer equipment will be offl ine for installation of new equipment from June 3 to 15. During this period, computer operations will be conducted in Room 108. At the same time, we are scheduled to train fi ve new employees. However, the room is too small to accommodate computer operators, trainers, and trainees at the same time.

3. We request that you delay sending us trainees to operate computer equipment until after June 15. Our main network of computer equipment will be offl ine for installation of new equipment from June 3 to 15.

During this period, computer operations will be conducted in Room 108. At the same time, we are scheduled to train fi ve new employees. However, the room is too small to accommodate computer operators, trainers, and trainees at the same time.

LESSON 3



Transition Words and PhrasesUsing the following list of linking or transition words and phrases will achieve greater unity and logical progression when organizing ideas.

Cause and Effect

Because Accordingly It follows that

Therefore Subsequently For this reason

Addition

And Moreover In addition

Again Furthermore Also

Instance

For example In particular In general

For instance At times Usually

Condition

If Although Even though

While Because When

Comparison/Contrast

But However Nevertheless

Yet Conversely On the contrary

Similarly Concurrently At the same time

Time

After Then Subsequently

Meanwhile Finally Following

Later Immediately Next

Soon Before Last

Emphasis

In fact Most important Indeed

Above all Certainly Undoubtedly

Conclusion

Finally In conclusion Apparently

Therefore So As a result

LESSON 3



Basic Qualities of Effective Illustrations• Simplicity–Depict complex data diffi cult to describe, such as process fl ow, physical and

chemical characteristics, and analysis of material.• Clarity–Provide visual depiction of abstract qualities.• Relevance–Clarify textual discussion.

Tips on Using IllustrationsPurpose

1. Use illustrations to support written material or to reduce the number of words needed to express complex information, not to substitute for it.

2. Discuss the signifi cance of the illustration in the text.

Placement

3. Place illustrations in the text where they can be most useful to the reader—immediately preceding or following the text, or on a page directly opposite.

4. Insert illustrations in the appendix if they serve as reference and not as clarifi cation of text.

5. Leave as much white space as possible in the illustration.

Identifi cation

6. Identify illustrations by titles or headings, consecutive numbers or letters.

7. Cite the source in which the illustration originally appeared.

Types of IllustrationsTables

Tables present an orderly arrangement of information using rows and columns arranged according to any number of factors: time, cost, size, quality. Effective tables maximize readability by:

• Containing concise information• Including brief titles and subheadings to identify data• Identifying columns and rows bearing information• Using suffi cient white space within and around the illustration• Appearing on one page, if possible• Summarizing—through comments and labeled footnotes—symbols, sources of information,

trends, and exceptions

Example:

Temperature(degrees Celsius)

01020304050

423355065

0

Rate ofEnzyme Action

A.

LESSON 3



Bar Charts

Bar charts or graphs measure data either horizontally or vertically against criteria that can denote value, quality, time, quantity, magnitude, or other variable. Effective bar charts contain:

• Titles and captions for information• Horizontal bar units of measurement that begin at the left margin (point zero) and progress

to the right• Vertical bar units of measurement that begin at the lower left margin and progress upward

Example:

40

20

18

16

14

12

10

8

6

4

2

045 50 55 60 65 70

No. ofSpecimens

Energy Absorbed, J

LESSON 3



Multiple Bar Charts

Multiple bar charts compare two or more variables rather than one. The bars can be distinguished by shade, hatch, tone, or color to avoid confusing the reader. The same guidelines for bar charts apply to multiple bar charts.

Example:

100

80

60

40

20

0

0 5

Time in Minutes

Tem

per

atu

re, C

Liquid A Liquid B

LESSON 3



Line Chart

Line charts show the importance of data by measuring change and growth and by indicating trends, cycles, and movements. Line charts use grids composed of a horizontal line (X axis), which plots time, and a vertical line (Y axis), which plots values. The writer indicates the relationship of the data being measured by plotting points that meet at right angles on the grid.

To devise a line chart:

1. Divide the horizontal and vertical axes into equal parts or units.

2. Note the zero point at the lower left corner of the chart.

3. List progressions in value on the vertical axis, beginning at the bottom and moving upward.

4. Print titles and captions horizontally.

Example:

100

80

60

40

20

00 1 2 3 4 5 6 7 8 9 10

Time in Minutes

Tem

per

atu

re, C

Liquid A Liquid B

LESSON 3



Flow Charts

Flow charts indicate the sequence of a process or activity from start to conclusion. Flow charts use lines, arrows, and boxes to indicate the fl ow direction.

Example:

DuringOperation

DetailedProcedures

TroubleshootingDiagrams

TroubleshootingLogic Trees

(Summary Procedures)

DuringScheduled or

On-Condition Maintenance

Go to MaintenanceAction PreciseSymptom List

Include inMaintenance

Procedure

MaintenanceAction PreciseSymptom List

Refer toTroubleshooting

Procedures

Troubleshooting Method

FaultDiscovery

1

TroubleshootingData Entry

2

TroubleshootingAccomplishment

3

LESSON 3



Drawings and Photographs

Technical writing uses drawings and photographs to display physical relationships, conditions, dimensions, position, size, shape, and texture. Clarity and simplicity in drawings and photographs are essential to effective visual presentation.

Examples

LESSON 4



ResourcesRevising, Editing, and Proofreading TechniqueGood writing requires rewriting to communicate the writer’s thoughts effectively. Below is a checklist for revising, editing, and proofreading technical writing.

Revise for Content

1. Is the purpose clearly stated?

2. Is any vital information missing?

3. Is any information extraneous?

4. Is any information repeated unnecessarily?

5. Are illustrations clearly presented and integrated with the text?

Revise for Organization

6. Is information presented in order of importance to the reader?

7. Does the organization of the sections and paragraphs contribute to the fl ow of ideas?

8. Do transition words link sentences and paragraphs?

Edit for Readability and Style

9. Are conclusions and recommendations emphasized?

10. Are the sentences clear?

11. Is the phrasing concise?

12. Is the tone appropriate for the situation and the readers?

13. Has necessary jargon been explained?

14. Has unnecessary jargon been eliminated?

Proofread for Overlooked Errors

15. Are the grammar and word usage correct?

16. Are the punctuation, abbreviation, and number usage correct?

17. Is the spelling correct?

LESSON 4



Writing for Another PersonTechnical writers often must submit for review their work to another person such as a supervisor or technical editor. Editorial comment is intended to improve the writing, yet it can be a frustrating aspect of the writing process if the critical commentary has more to do with personal style than content or structure.

One way to offset problems or critical disagreement with reviewers, editors, and supervisors is to establish a mutual understanding of the purpose, goals, content, structure, and preferred style of the writing assignment. Ask questions at the beginning: What is to be included? Emphasized? Limited? Avoided? Who are the likely readers?

Then, if even after writing according to mutually understood guidelines your writing is still criticized, look for clues in the editor’s comments to preferences or dislikes: short paragraphs? Lists? Lots of illustrations? Favorite phrases, buzzwords, jargon?

This approach will make subsequent writing assignments productive, effective, and less stressful.

LESSON 4



Basic Elements of Longer Formats

1. Letter of Transmittal–This letter, which is similar to a cover letter, offers the reader an overview of the report’s scope, purpose, and selected key fi ndings, observations, conclusions, or recommendations that will enhance the reader’s understanding of the report. Letters of transmittal include acknowledgements of appreciation for any assistance the writer received; indicate limitations such as time, money, or personnel; explain criteria or methods of investigation; or urge action.

2. Title–Technical report titles should be brief and accurate, composed of key words that clearly describe the content and focus. Since titles serve as clues to content, they must not be vague, inexact, or too general.

Example:

Vague Title Precise Title

• The Electronics Industry • Sales Trends in Offi ce Computer Equipment

• Training Procedures • Training Procedures for Chemical Engineers

3. Circulation/Distribution List–The list should be included if the report is intended primarily for particular recipients or groups within an organization. Should the report contain classifi ed or restricted information, note this on the list.

4. Table of Contents–Formal or lengthy technical reports often include a contents page that guides the reader to the various topic headings and section divisions. Contents pages include appropriate page reference numbers. While the format may vary among organizations and writers, contents pages denote prefatory material such as glossaries and abstracts, major headings, primary and secondary subdivisions, any material contained in appendices, and a bibliography or list of references.

5. List of Illustrations–A list of illustrations (tables, graphs, charts, drawings, photographs, etc.) is placed after the contents page. Technical reports tend to distinguish between tables and fi gures. These lists include page numbers and specifi c titles.

6. Abstract/Summary–Due to the complexity of their content and variety of readers, technical reports include abstracts or summaries of key points. Traditionally, an abstract represents 10 percent or less of the total report length. While some abstracts are contained in a paragraph or two, others will require two or three pages. Abstracts are prepared after the fi nal draft to allow for changes and to ensure completeness.

7. Introduction–A good introduction outlines the purpose, topic, major focus of fi ndings, and selected background information. In an introduction, the writer provides a frame of reference while avoiding an overwhelming amount of detail. An introduction determines the direction and sets the tone of a report. It is not an abstract; rather, it provides continuity to the developing of ideas.

8. Discussion/Findings–This section details the problems, procedures, costs, fi ndings, and observations relevant to the purpose. Included are the discussion of a specifi c process, comparison of one method with another, analysis of a problem, and comments on the feasibility of a future project. Any detail that can explain, illustrate, or elaborate on the premise noted in the introduction should appear in this section.

9. Conclusion–A valid conclusion refl ects the views drawn from facts, opinions, analyses, and other observations. The conclusion should bear a logical relationship to the data and information that precedes it, and not be forced or based on a preconceived notion or misinterpretation of facts. Conclusions, which may be numbered, are listed in order of importance or in the order in which previous evidence has been presented.

LESSON 4



10. Recommendations–Recommendations suggest a course of action based on previous observations and conclusions. Recommendations must be clearly worded and presented in the same order as the conclusions that precede them. The tone of recommendations should be confi dent and emphatic if the reader is to be convinced they represent the best course of action regarding the topic.

11. Bibliography–Technical reports often require research. In such cases, compile a bibliography of all reference sources. These include books, magazines, journal articles, newspapers, encyclopedias, previous studies, and reports.

Example: Jones, Jasper. Concepts of Electrical Engineering. New York: Global Publishing Company, 1990.

12. Glossary–A glossary is a list of defi nitions of technical words, phrases, terms, and concepts that are unfamiliar to nonexpert readers. Defi nitions should be clear and precise, and they should not contain other technical terms that might prove confusing.

13. Illustrations–Illustrations are added to clarify, not clutter, technical reports. Illustrations should not be substituted for text; rather, they should support or simplify diffi cult concepts.

14. Appendix–All material supplementary to the report’s purpose and fi ndings appears in an appendix that follows the text. Charts, letters, memos, questionnaires, interviews, fi eld notes, previous studies, numerical data, and other information that is relevant but not essential to understanding the report can be included in an appendix. Selectivity is the key to compiling a useful appendix.

LESSON 4



Technical ManualsTechnical manuals provide instructions for assembling, operating, maintaining, and overhauling equipment. These manuals also offer instructions in carrying out procedures.

Aspects of Effective Technical Manuals: Effective technical manuals should:

1. Mirror the user’s experience level.

2. Contain all required information (e.g., tools, equipment, personnel required, warnings).

3. Structure information logically.

4. Present easily scannable information.

5. Include accurate, reliable, valid data.

6. Express information clearly and precisely.

7. Provide practical instruction.

8. Refl ect the most effi cient way to perform the task.

9. Employ simple, relevant illustrations.

Format of Technical Manuals

Technical manuals are organized into divisions and subdivisions or chapters and sections to provide information that is easy to understand, locate, and correlate with equipment or tasks.

Manuals are divided into parts to separate coverage for various maintenance levels or to distinguish tasks. Parts of manuals should be divisions of the volume and not separate entities.

Technical manuals are usually organized according to the following format:

• Title• Contents Page

A. Front Matter/IntroductionB. Checklist of Tools or ItemsC. Parts

• Chapters• Sections/Subdivisions• Paragraphs• Illustrations

D. AppendicesE. GlossariesF. Index

LESSON 4



Titles and Headings: Titles and headings should be precise and brief.

Examples:

Part One: Emergency Auxiliary Equipment

Chapter 5–Tank Operating Instructions

Section 1. Mixing Controls

How-to-Use-This-Manual Information: This section of the manual describes the content, format features, use, and value to the user.

This section should contain information that:

1. Provides information essential to using the manual effectively

2. Explains any unusual or unique aspects of the manual

3. Emphasizes the benefi ts of the manual

Placement: How-to-use information is generally contained in a separate section at the beginning of technical manuals. For complex manuals, it is often helpful to the user to provide this information at the beginning of each major division or section.

Format: The how-to-use information contains:

• A usage statement, example:

Before beginning any tasks for this equipment, you must familiarize yourself with the procedures in Section 1.

• An overview that provides a general description of the entire manual and explains important features of the contents and organization of material

• A contents page, located in the front of the manual that lists chapter, section, and major topic titles; example:

Maintenance Manual for Equipment CarriersPage

How to Use This Manual ............................................................................ ii

Chapter 1 Introduction ............................................................ 1Section I General Information ................................................................... 5

Section II Equipment Description .............................................................. 7

Chapter 2 General Principles of Operation ..........................10Section I Major Systems ............................................................................ 12

Section II Tools and Equipment ............................................................... 18

Section III Preventive Maintenance Checks ............................................. 21

LESSON 4



• Indexes located in the front of the manual, which include: – Section Index – Symptom/Problem Index – Maintenance Information Index

• An alphabetical index located at the end of the manual, which can include:

Codes Headings Symptoms

Names Indicators Tasks

Controls Part numbers Test equipment

Equipment terms Procedures Tests

Functions Serial numbers Titles

An Effective Index:

1. Tells the user where information is located within the manual

2. Enables the user to fi nd an item under any name likely to be used for that item

3. Lists entries in plain language and contains multiple entries (e.g., Files, Backing Up, and Backing Up Files)

4. Uses consistent terminology to avoid confusion (e.g., “Fuel Gauge Reads Empty,” not “Gas Tank Is Empty”)

Example:

Symptom IndexCooling System

Page

RadiatorBoils over .................................................................................................. 75

Leaks ......................................................................................................... 76

Temperature GaugeNo indication ........................................................................................... 80

Runs cold .................................................................................................. 81

Runs hot ................................................................................................... 82

LESSON 4



Content and Style Requirements: Technical manuals provide detailed procedures to guide the user through various stages: assembling, operating, and maintaining or testing. Detailed procedures include:

1. Initial setup, or what to do before starting the procedure

2. A general description of technical principles to increase the user’s technical knowledge and understanding of the task

3. Descriptions of parts, materials, personnel required, tools, special equipment or environmental conditions, and cautionary or safety instructions

Example:

Tools:

– Wrench – Pliers – Chain hoist

Equipment Conditions:

– External power must be provided to the vehicle.

Warnings and Cautionary Notes

Technical manuals include warnings and cautionary notes to alert the user to conditions, practices, or procedures that must be observed to avoid personal injury, health hazards, equipment damage, or operation disruption. Warning and cautionary notes should be PRECISE:

• Prominent–distinguished easily from other text• Readable–laid out in easy-to-follow steps• Emphatic–forceful in their warnings• Complete–thorough in detailing the dangers and precautionary measures• Instructive–helpful in guiding the user through the precautionary measures• Specifi c–exact in listing the sources of danger, the consequences, and the contingencies• Expressive–described in clear, concise, and simple English

Example:

WARNING: CAUSTIC CHEMICALS IN BATTERIES. Use rubber gloves, goggles, and apron to avoid severe burns.

– If chemicals get on your skin, clothes, or equipment, wash immediately with water. – If chemicals get in your eyes, wash them with plenty of water and get medical help

immediately.

LESSON 4



Readability

The best technical manuals are, above all else, readable. Obstacles to easy reading include:

• Wordy and awkward writing style• Lengthy sentences and paragraphs• Diffi cult-to-fi nd information• Cumbersome cross-referencing• Unexplained jargon• Poor integration of text and illustrations

Guidelines for Ensuring Readability

1. Consider the user’s technical limitations by choosing familiar words and terms.

2. Use simple rather than complex sentences.

3. Limit paragraphs to a single main idea.

4. Use illustrations whenever helpful.

5. Simplify complex sentences and paragraphs by using lists.

Instead of: The steering system consists of a steering wheel, forward steering tube, steering quadrant, a transverse steering rod, and two levers and plates.

Use list format: Steering system consists of:1. Steering wheel

2. Forward steering tube

3. Steering quadrant

4. Transverse steering rod

5. 2 levers

6. 2 plates

Attention-Getting Devices: Technical writers use the following devices for attracting attention to important details, locating information, or conveying the relationship among pieces of information:

• Different type sizes• Boldface• Underlining• Italics• Indenting• Arrows• Color

Examples:

Note: If the equipment has been stored or allowed to get damp, the insulation surrounding the wires must be checked.

Shut off the unit and disconnect the wires.

LESSON 4



Technical ProposalsTechnical proposals describe how a job, process, procedure, research, or service will be performed. Simple proposals may appear in memo or letter format; complex proposals may require another standardized format. Whether informal or formal, all proposals have the same goal: to sell an idea, product, service, or procedure, or to offer a solution to a specifi c problem either within an organization or to an outside one.

Format

Technical proposals typically follow this format:

Title Page

I. Table of Contents

II. IntroductionProvide a summary of the background and importance of the proposal. Include a purpose statement that defi nes the approach and scope. Mention facts, fi gures, or other points that establish the need for your proposal. Emphasize the benefi ts to be gained. Attract your reader’s interest by reinforcing the importance of your approach.

III. Scope

– State overall objectives and goals. Provide a rationale for your proposal. – List and discuss materials and methods. – Outline a breakdown of tasks or work stages. – Provide a schedule for completing the work.

IV. Qualifi cations – Detail your experience, education, and other qualifi cations. – Indicate success or experience in performing or overseeing similar tasks/projects. – Provide a staffi ng plan. – Describe the experience and qualifi cations of supporting personnel.

V. Evaluation ProceduresDescribe procedures such as progress reports, site visits, or tests that will be used for evaluating the project at various stages.

VI. ConclusionSummarize key benefi ts of your proposal. Convince the reader to accept your proposal based on your experience and approach.

VII. AppendixInclude relevant material to support your proposal.

Writing Style

The style of effective technical proposals should combine attention to clarity and detail with logical organization. The writer’s tone should project confi dence and objectivity while avoiding overstatement or exaggeration.

LESSON 4



Sample Informational Report

The Technology of Recycling

AbstractSince the 1980s the technology of recycling has been the most important method of disposing of waste. According to environmental experts concerned about land, water, and air pollution, recycling is the best alternative to traditional disposal methods such as burying or burning garbage. Recycling also lessens the growing scarcity of landfi ll space. Recycling of paper, glass, aluminum, copper, and plastics turns waste into potential resources. Recycling involves three phases: (1) sorting recyclables, (2) processing them, and (3) creating new products from various waste materials.

IntroductionIn response to the increasing amount of garbage discarded in the United States, environmental scientists and business leaders have identifi ed recycling as the single most effective solution to garbage disposal. Recycling is an old technology. Glass, paper, and steel have been recycled since the 19th century, yet new technologies and new waste products have created a need for a method that will both improve recycling and address environmental concerns. Modern recycling technology involves sorting recyclables, processing them, and creating new products from waste.

The Recycling ProcessThe recycling process varies depending on the composition of the recyclables’ material.

Sorting GarbageRecyclables, such as paper, glass, yard waste, plastic, aluminum, wood, rubber, and leather, must be separated or sorted from other trash and from toxic-bearing materials such as paints and pesticides. To accomplish this phase, garbage must be sorted before being placed for curbside pick-up. Sanitation offi cials often mail brochures or fl yers to local residents advising them of materials that are not recyclable, such as photographs and fi lm.

Processing GarbageNewspapers, typing paper, computer printouts, and cardboard are among the paper products that are processed by a series of steps. First, the paper is deposited into a huge vat of water and chemicals, where the inks are removed and the papers are blended into a mass or bulk of wet pulp. Then the pulp is drained of water and new paper is created, dried, and pressed by machines before being wound into huge rolls designed for shipping.

Two types of metal are recycled. Aluminum includes beverage cans, pie plates, and frozen-food trays. Steel includes automobiles, machinery, refrigerators, and structural beams. Powerful machines pulverize, crush, shred, or fl atten the metals. The metal is then melted at intense temperatures in large furnaces and cast into new various forms.

Glass fi rst must be sorted according to color. Glass is processed by being fed into a machine that crushes and grinds the glass into tiny fragments, then it is mixed with sand and other materials and melted into a fl uid mass in a glass-making furnace. As the molten glass is removed from the furnaces, machines mold the glass into new shapes, bottles, bowls, and other containers.

Plastics pose a problem in recycling because different types of plastics are composed of different elements (polymers). As a result, discarded plastic must be sorted according to the different elements, which is both expensive and time consuming. Recycling research has attempted to solve this problem by developing various techniques to test plastics for their elements, to separate milk containers and egg cartons from soda and vegetable oil bottles.

Creating New ProductsThe last phase of recycling is the creation of new products from discarded waste, materials that range from stationery and cereal boxes to soda and beer cans are used to make bottles and computers and televisions.

LESSON 4



Sample Proposal Report

Improving Graphics Presentations

1.0 Summary

Technology is available for improving presentation graphics in engineering reports.

2.0 Introduction

Current desktop publishing and graphics software technology can improve the quality and simplify the preparation of presentation graphics used in engineering reports and manuals. Single, simple color charts and overhead transparencies may require less than one half hour to prepare, while more complicated illustrations require some additional time and effort. Acquiring a computerized graphics system will both facilitate the speed with which illustrations are prepared and enhance the overall quality of the presentation.

3.0 Functions of Desktop Publishing and Graphics Programs

Combined desktop publishing and computer graphics programs can perform the following functions:

3.1 Page Makeup: Text format may be designed with any typeface, size, and column width to allow greater fl exibility in designing reports and manuals.

3.2 Scanning: Any print image, text, or photograph can be scanned into a computer fi le for enlarging, placement, or shrinking.

3.3 Computerized Graphics: The software for graphics illustrations enables the user to create three-dimensional color diagrams, circles, bar charts, or graphs and to choose from pre-designed images, such as an arrow or human fi gure, that are included in the software art package.

3.4 Conversion of Data into Graphics: Various graphics software can convert raw data into tables, pie charts, and graphs.

4.0 Hardware Equipment

The following hardware equipment is essential to operating current available desktop publishing and computerized graphics programs:

4.1 Computer with ample hard disk space for presentation graphics programs

4.2 Color monitor with high resolution and an oversized screen that assures both user visual comfort and greater ease in viewing images

4.3 Mouse that allows for easier drawing, moving, copying, and controlling the graphics options

4.4 Scanner that can copy text and images

4.5 Laser color printer to enhance high-quality visual presentations

5.0 Choice of Publishing and Graphics Software

The main consideration regarding choice of software is compatibility with hardware, current fi le formats, and daily needs.

6.0 Conclusion

Recommend acquiring a desktop publishing and computerized graphics presentation hardware and software program to assist engineers in preparing effective reports and manuals that will refl ect greater clarity and visual appeal.

LESSON 4



Reading ListBlake, Gary, and Robert Bly. The Elements of Technical Writing. New York: Macmillan, 1993.

Boiarsky, Carolyn R. Technical Writing: Contexts, Audiences, and Communities. Boston: Allyn and Bacon, 1993.

Bowen, Mary E., and Beverly Schneller. Writing About Science. 2nd ed. New York: Oxford University Press, 1991.

Day, Robert A. How to Write and Publish a Scientifi c Paper. 3rd ed. Phoenix: Oryx Press, 1988.

Dodd, Janet S., ed. The ACS Style Guide: A Manual for Authors and Editors. Washington, DC: American Chemical Society, 1985.

Flaherty, Stephen M. Technical and Business Writing: A Reader-Friendly Approach. Englewood Cliffs, NJ: Prentice Hall, 1990.

Houp, Kenneth W., Thomas E. Pearsall, and Elizabeth Tebeaux. Reporting Technical Information. 8th ed. Boston: Allyn and Bacon, 1995.

Iacone, Salvatore J. Write to the Point. Franklin Lakes, NJ: Career Press, 2003.

Lindsell-Roberts, Sheryl. Technical Writing for Dummies. New York: Hungry Minds, 2001.

Mathes, J.C., and Dwight W. Stevenson. Designing Technical Reports. 2nd ed. New York: Macmillan, 1991.

McQuaid, Robert W. The Craft of Writing Technical Manuals. 2nd ed. San Diego: R.W. McQuaid, 1990.

Michaelson, Herbert B. How to Write and Publish Engineering Papers and Reports. 3rd ed. Phoenix: Oryx Press, 1990.

O’Connor, Maeve. How to Copyedit Scientifi c Books and Journals. Philadelphia: ISI Press, 1986.

Quattrini, Joseph A. Clear and Simple Technical Writing. New York: Prentice Hall, 1986.

Reep, Diana. Technical Writing: Principles, Strategies, and Readings. Boston: Allyn and Bacon, 1991.

Rutherfoord, Andrea J. Basic Communications Skills for Electronics Technology. Englewood Cliffs, NJ: Prentice Hall, 1989.

Shelton, James H. Handbook for Technical Writing. Lincolnwood, IL: NTC Business Books,1994.

Sherman, Theodore A., and Simon S. Johnson. Modern Technical Writing. 5th ed. Englewood Cliffs, NJ: Prentice Hall, 1990.

Sides, Charles H. How to Write and Present Technical Information. Phoenix: Oryx Press, 1991.

LESSON 4



Van Laan, Krista, and Catherine Julian. The Complete Idiot’s Guide to Technical Writing. Indianapolis: Alpha Books, 2001.

Vassallo, Philip. The Art of On-the-Job Writing. Portland: First Books, 2005.

Vassallo, Philip. The Art of E-mail Writing. Portland: First Books, 2007.

Vassallo, Philip. How to Write Fast Under Pressure. New York: AMACOM, 2010.

Weiss, Edmond H. How to Write a Usable User Manual. Philadelphia: ISI Press, 1985.

Wolcott, Harry F. Writing Up Qualitative Research. Newbury Park, CA: Sage, 1990.

Zeleznik, Julie M., et al. Technical Writing: What It Is and How to Do It. New York: Learning Express, 1999.

Zimmerman, Carolyn M., and John J. Campbell. Fundamentals of Procedure Writing. Columbia, MD: GP Publishers, 1987.

Documents

Effective Technical Writing6e21898d22ccea8d172c-9c864806c5e4c14e9b6f9c418f488ed3.r59.cf1.rackcdn.com/... · L1.4 Effective Technical Writing 7. Meeting Report Opening – Purpose–What