Technical Writing

Technical Writing

Vasile Nistor PhD

Assistant Professor

BioMedical Engineering

CEAS / SEEBME

Discourse & Rhetoric

• Latin: discursus – “running to and fro”– describes written and spoken communication

• Rhetoric - the art of discourse– Greek - ῥητορικός (rhētorikós)– aims to improve the facility of speakers/writers who

attempt to:– inform, – persuade, – motivate – particular audiences in specific situation

Why Technical Writing?

• Build on existing knowledge• Propagate the knowledge

– Co-workers/Team members– Sales/Marketing personnel– Customers

• Technical Work ≠ Technical Writing

Technical writing

• Journal paper• Thesis• Dissertation• Report

Rhetoric HOW WRITING WORKS

The job of any piece of writing is to move the reader from one understanding of a topic to a new understanding.

BA


BA

Consider this example:

if you wanted to slide a box across a floor to a specific spot . . .


BA

You could figure out the amount and direction of the force you would need to apply to the box to get it to move to that spot by knowing a few things . . .


Mass

Gravity

Distance

Friction

Applied Force

By understanding something about the forces exerted on the box and by having a good idea of where you wish to go, you could move the box in a predictable way.

New Location

Rhetoric

Reader

MessageWriter

HOW WRITING WORKS

Purpose

The same is true in writing: by knowing something about the elements involved in the reading act you can predictably influence the outcome.

A B

Know your Audience !

• Who is going to read the report?• What is the level of their current knowledge?• How much information is needed?• What background information to include?• Why is the reader reading the report?• Is the document supposed to inform or

convince?• How much time does the reader have to read it?

Rhetoric

Who is theReader?

What is theMessage?

Who is theWriter?

ReadingAct

HOW WRITING WORKS

Who is the reader?

What do they need to know?

What do they already know?

What do they want to know?


What is the message?

What data / evidence is necessary to support this purpose?

What is the purpose of writing?


• Inform• Persuade• Motivate

What does the text say about the writer?


Who is the writer?

Every piece of writing produced, like it or not, presents the reader with a picture of the writer. This picture can leave a positive or negative impression on the reader.

What picture does the text present of the writer?

•Knowledgeable?•Clear and Fluent?•Authoritative?


Who is the writer?

• Mechanical errors?• Inconsistent tense• Uneven or inappropriate tone?• 1st or 2nd person (versus 3rd person)?


Who is the writer?

What picture of the writer does the text present?

Report Format

STYLE AND FORMAT CONSIDERATIONS

Unless otherwise directed, adopt a format style from a publication in your discipline:Nearly every engineering discipline has authoritative journals. These publications have specific formatting styles either explicitly defined in a style guide or implicitly present in examples from the publication.

Report Format

STYLE AND FORMAT CONSIDERATIONS

Use a Journal Model for:

• Required Elements• Citation Style• Figure and Table Style

Report Format

COMPONENTS OF A TECHNICAL REPORT

Abstract / Executive SummaryIntroduction

Body

Summary/Conclusion/Recommendations

Report Format

Abstract or Executive Summary

A distillation of the whole of piece of writing

How are they used?

What information can I expect to find in this report?

Report Format


Examples are available at www.eng.odu.edu/edservices.htm

AbstractIn this paper, a novel location management scheme, distributed mobile tracking (DMT), is proposed for routing improvement in Cellular IP networks. A mobile-tracking tree (MT-Tree) for each active mobile host is established by tracking the movement of the host in DMT. Two mechanisms, pruning process and growing process, are also proposed to improve DMT. Packet transmissions can follow the route on the MT-Tree instead of using the gateway route. Simulation results have shown that DMT has the advantages of shorter routing paths as well as load balance for wired links over the original gateway-based location management scheme. Moreover, three multicast protocols for Cellular IP are proposed: GBMP, GBMP-RO, and MTMP. In GBMP, the gateway is responsible for group management as well as multicast transmission. Multicast packets received by the base station are first forwarded to the gateway. The gateway then forwards the packets to each member of the group by multiple unicasting. GBMP-RO, a modified version of GBMP, adopts the idea of source routing for multicast transmissions. MTMP is mainly based on the MT-Tree routing scheme. However, if not all group members can be covered by MT-Tree routing, MTMP will instead adopt GBMP-RO for multicast transmission. Simulation results demonstrate that MTMP has the advantages over GBMP and GBMP-RO in terms of load balance in the Cellular IP network. Author Keywords: Location management; Cellular IP; Routing; Multicast

The design project group at AMCE Engineering is involved in the design of a new widget to reduce the cost of our satellite communication system. The present version of the widget has been identified as the cause of the AMCE communicator’s low market share. The design group of which I am a member has been given the task of redesigning the widget to reduce its cost. The group has determined three different approaches to solving the problem: 1. Use less costly components in the D/A converter section of the receiver unit and redesign the control unit.2. Go to an outside vendor and substitute an “off-the shelf” controller unit, which may have marginal specifications.3. Increase the size of the power supply system so that a single power supply can handle more than one receiver/transmitter unit. This reduces the number of power supplies and, hence, reduces the cost. Evaluation of these options, including cost evaluation and technical assessments of each, results in the following recommendations: Due to reliability and technical feasibility, it is recommended that AMCE Engineering accept solution 3. Solutions 1 and 2 should be rejected because the components needed for these solutions will not have sufficient reliability to make them cost effective.

Executive Summary

Abstract / Executive Summary

Purpose• What is your reason for writing?

• What is your main idea?

Scope• What is your focus in this piece?

• Where do you concentrate your attention?

Method

• What kinds of evidence do you provide?

• How do you try to convince the reader of the validity of your main idea?

Results

What are the consequences of the problem or issue that you are discussing?

Recommendations

• What solutions do you present to the reader to resolve the problem or issue in the piece?

• Do you recommend action or change? Conclusions

• Do you describe a 'cause and effect' relationship or explain the origins of this issue or problem?

• What conclusions do you draw from study of the issue or problem?

Report Format


Introductions and conclusions should be

closely linked.

Introductions ask the questions and pose the problems. Conclusions

state the answers.

Introduction

Conclusion

Introduction:

Sets the context, poses the problems, and asks the questions that will be answered in the

body of the paper. These questions

may be implied or stated overtly.

Report Format


Introduction

Introduction:

What goes into it?

Report Format


• Why are you presenting this work?

• Where does it fit in the engineering field?

• How does it relate to other

work in the field?

• What are the aims

and objectives

of the

project?

Introduction:

What goes into it?

Report Format


Set up contextDefine scope

Foreshowing / mapping

State problem/thesis/question

Introduction:

What goes into it?

Report Format


Foreshowing / mappingRepetition is necessary for cognition, Repetition is necessary for cognition,

Repetition is necessary for cognition, Repetition is necessary for cognition,




Repetition is necessary for cognition,


Repetition is necessary for cognition,,


Repetition is necessary ,

Repetition is necessary Repetition is necessary for cognition,


Conclusions The

conclusion answers

the questions asked in the

Introduction by connecting those questions with the

data / evidence supplied in the body. Therefore, it should be closely related

to the objectives that were stated in the introduction.

Report Format


Conclusions

Summarize Key points

State Conclusion

State Relevance

Give recommendations for further actions

Report Format


Conclusions





Repetition is necessary for cognition, Repetition is necessary for cognition, Repetition is necessary for cognition,





Repetition is necessary for cognition, Repetition is necessary for cognition

Report Format


Summarize key points

Body

Report Format


The content of the body of your writing is determined by the assignment and purpose for doing the writing in the first place.

Possible elements include:

• Theory • Review of literature• Experimental method • Results • Discussion

Report Format


Body

Summary

How is a summary used?The summary is a distillation of the whole of your work. A summary restates and reemphasizes key points of the message. A good summary should guide the readers’ understanding of the text.

Report Format


Recommendations

A recommendation is a statement that some action be taken or not taken. These statements should be supported by the content of the paper. Recommendations tell the reader what they should do next.

Report Format

COMPONENTS OF A TECHNICAL REPORTHow are recommendations different from conclusions?

Report Format


Abstract / Executive SummaryIntroduction

Body

Summary/Conclusion/Recommendations

Where Do I Start? FIRST, KNOW YOUR STUFF!

Strategies for beginning to write a technical report

• Arrange the results of your research (formulas, graphs, charts, etc) in a logical sequence. Write explanations for each element.

• FORM DRIVEN: Create a rough outline of the body of your report, “flesh it out” as best you can, and then work on the other parts.

• CONTENT DRIVEN: Write down each of the components and try to “fill in the blanks” by answering the questions provided in this presentation

Proofreading and Revision

The difference between proofreading and revision

Revision asks you to look at your work again (re-vision, re-view, re-envision) through the eyes of your audience. ( DO THIS THROUGH OUT THE WRITING PROCESS, BUT DON’T LET IT GET YOU BOGGED DOWN)

Proofreading is checking for mechanical (grammatical) problems and completeness. (DO THIS LAST, DO THIS ONCE)

NO, THEY’RE NOT THE SAME!

Does your writing say what you think it says?

Do the various parts of your writing fit together?

Do the various parts of your writing do their jobs?

Proofreading and Revision

Revision WHY DO IT?

Assignment

• Three paragraphs, 200 words max• Identify your audience• Identify the writer/s• What is your message

Elements and StandardsA technical report follows a specific layout and format as specified by the American National

Standards Institute (ANSI)

Technical Report Writing

The Importance of WritingProject Leadership

Project Engineer

Engineers perform technical writing to communicate pertinent information that is needed by upper management to make intelligent decisions that will effect a company’s future. Detailed

Knowledge

Decision Control

Many engineers spend between 1/3 and 1/2 of their work time engaged in technical writing. Examples include:

• proposals• regulations• manuals• procedures• requests

• technical reports• progress reports• emails• memos

The Importance of Writing

Technical Writing

Technical writing is a type of expository writing this is used to convey information for technical or business purposes.

Technical writing is NOT used to:

• entertain• create suspense• invite differing interpretations

Technical Report Layout

Front Matter

Text

Back Matter

Bac

k C

over

List

of

Sym

bols

, Abb

revi

atio

ns,

and

Acr

onym

s

App

endi

xes

Ref

ere

nces

Con

clus

ion

Res

ults

and

Dis

cuss

ion

Met

hods

, Ass

umpt

ions

, an

d P

roce

dur

es

Intr

oduc

tion

Sum

mar

y

List

of T

able

s an

d F

igur

es

Tabl

e of

Con

ten

ts

Abs

trac

t

Titl

e P

age

Fro

nt C

over

Front Matter

The front matter is used to help potential readers find the report.

Once found, the front matter will help the reader to quickly decide whether or not the material contained within the report pertains to what they are investigating.

1. Cover*

2. Label*

3. Title Page

4. Abstract

5. Table of Contents

6. Lists of Figures and Tables

Front Matter

*May be an optional element

A cover and label are used if the report is over 10 pages long.

The cover (front and back) provides physical protection for the printed report. Plastic spiral bindings and thick, card-stock paper are recommended.

Front Matter: Cover*


Front Matter: Label*

• Report title and subtitle (if a subtitle is appropriate)

• Author’s name• Publisher*• Date of publication

A label is placed on the cover to identify:

The title page provides descriptive information that is used by organizations that provide access to information resources (i.e., library).

A title page duplicates the information found on the front cover (if one is used).

Front Matter: Title Page

An abstract (informative style) is a short summary that provides an overview of the purpose, scope, and findings contained in the report.

Purpose - identifies the issue, need, or reason for the investigation

Scope - reviews the main points, extent and limits of the investigation

Findings - includes condensed conclusions and recommendations

Front Matter: Abstract

• no more than 200 words*• provides an “in a nut shell”

description without providing underlying details

• contains no undefined symbols, abbreviations, or acronyms

• makes no reference by number to any references or illustrative material

Front Matter: Abstract

ii

The table of contents lists the title and beginning page number of each major section within the report (excluding the title page and the table of contents).

Front Matter: Table of Contents

iii

A list of figures and tables helps the reader to locate illustrations, drawings, photographs, graphs, charts, and tables of information contained in the report.


Front Matter: List of Figures and Tables*

iv


A figure is any drawing, photograph, graph, or chart that is used to explain and support the technical information in the text.The figure number and title will appear below the image.Refer to a figure or table within the text, and place the image close to the reference.



A table is an arrangement of detailed facts or statistics that are arranged in a row-and-column format.

The table number and title appear above the table.


The text is the part of a technical report in which the author describes the methods, assumptions, and procedures; presents and discusses the results; draws conclusions, and recommends actions based on the results.

Text

• Summary• Introduction• Methods, Assumptions, and Procedures• Results and Discussion• Conclusions• Recommendations*• References

Text


•States the problem, method of investigation, conclusions, and recommendations

•Contains no new info that is not contained in the report

•Does not contain references

Text: Summary

1

The Introduction prepares the reader to read the main body of the report.

This page focuses on the subject, purpose, and scope of the report.

Text: Introduction

3

Subject - defines the topic and associated terminology; may include theory, historical background, and its significance

Purpose - indicates the reason for the investigation

Scope - indicates the extent and limits of the investigation

Text: Introduction

Text: Methods, Assumptions, and Procedures

The methods, assumptions, and procedures used in the investigation are described so the reader could duplicate the procedures of the investigation.

Information in this section includes:

• System of measurement• Types of equipment used and accuracy• Test methods used

Text: Methods, Assumptions, and Procedures

MethodsHow did you discover the problem? What measuring tools were used? What

measurement system was used?

AssumptionsWhat do you think, but cannot substantiate as fact?

ProceduresHow did you gain a better understanding of the problem?

4

Text: Results and Discussion

The results and discussion section describes what you learned about the problem as a result of your research, identifies the degree of accuracy related to your findings, and gives the reader your view of the significance of your findings.

Text: Results and Discussion

ResultsWhat did you learn about

the problem through your research?

DiscussionHow accurate are your

findings? What is the significance of the results of the research?

6

Text: Conclusion

Restatement of Results What are the factual findings that resulted from your

research? What are you implying as a result of these findings?

Concluding RemarksWhat are your opinions

based on the findings and results?

9

Text: Recommendations*

A section called recommendations is often included in reports that are the result of tests and experiments, field trials, specific design problems, and feasibility studies.

The author may recommend additional areas of study and suggest a course of action, such as pursuing an alternate design approach.


Text: Recommendations*


Additional StudiesIs there information that

still needs to be learned?

Suggested ActionsWhat does the author want the reader to do with the

information?

12

Text: References

The references section is the place where the author cites all of the secondary research sources* that were used to…

• develop an understanding of the problem

• support the information contained in the report

14

Back Matter

The back matter supplements and clarifies the body of the report, makes the body easier to understand, and shows where additional information can be found.

• Appendixes*• Bibliography*• List of Symbols, Abbreviations, and

Acronyms• Glossary*• Index*• Distribution List*

Back Matter


Anything that cannot be left out of a report, but is too large for the main part of the report and would serve to distract or interrupt the flow belongs in the appendixes. Examples include:

• Large tables of data• Flowcharts• Mathematical analysis• Large illustrations

• Detailed explanations and descriptions of test techniques and apparatus

• Technical drawings


Back Matter: Appendixes*


Appendix AHose Nozzle Part Drawings

Back Matter: Appendixes*

Back Matter: List of Symbols, Abbreviations, and Acronyms*

If more than five symbols, abbreviations, or acronyms are used in the report, they are to be listed with their explanation.


Technical Journal Paper

.

Elements of a Technical Report•Title•Abstract (Executive Summary)• Introduction•Theory and Analysis•Experimental Procedures•Results and Discussion•Conclusion(s)•Acknowledgments•References•Appendix

Writing Style

•Depends on the audience•More Lively Writing (usually preferred)

– First Person, Active Voice, Past/Present Tense

•More Formal Writing – Third Person, Passive Voice, Past/Present Tense

•Never use slang

Writing Style•Use First-Person, Active Voice, Past Tense or Third-Person, Passive Voice, Past Tense

• Not Recommended: Clean the gallium arsenide substrates by boiling them in trichloroethylene.

• Not Recommended: I clean the gallium arsenide substrates by boiling them in trichloroethylene.

• Acceptable: The gallium arsenide substrates were cleaned by boiling in trichloroethylene.

• Recommended: We cleaned the gallium arsenide substrates by boiling them in trichloroethylene.

Writing Mechanics• Minimize the use of Acronyms• If Acronyms are necessary, always define them at the

first use• Number all equations, tables, and figures• All tables and figures must have captions.• All figures must have labeled axes• All quantities must have units

Writing the Report: An Approach• Decide on a title• Create a brief outline with only main section

headings• Create a more detailed outline with subheadings• Create an executive summary• Create the main body of text• Insert tables, figures, references, and

acknowledgements

Abstract or Executive Summary

• Think of it as a substitute for the report for a busy reader

• Length never less than three sentences or longer than a full page. Often 200 words.

• Sentence One: expand on the title• Sentence Two: why the work was done• Remainder: key results, with numbers as

appropriate, conclusions, recommendations

Introduction

• This is not a substitute for the report, and so does not echo the abstract

• Here is the place for context, relation to prior work, general objective, and approach

Theory and Analysis

• Briefly describe the theory relevant to the work

• Provide design equations• Include calculations and computer simulation

results • Provide values for all key parameters

Experimental Procedures

• Describe Apparatus and Materials• Show test setups• If this section is well written, any electrical or

computer engineer should be able to duplicate your results.

Results and Discussion

• Use tables and graphs• Consider moving large quantities of raw data,

detailed derivations, or code to an appendix• Methods of plotting which produce well delineated

lines should be considered• Results should be critically compared to theory• Consider limitations in the theory and engineering

tolerances

Conclusion

• Similar to executive summary• Must be concise• Reinforces key ideas formed in discussion• Includes recommendations for future work,

such as implementation of a design

Figures and Tables

• Every figure must have a caption• All tables must have a title• Figure/tables are placed after they are mentioned

in the text (all must be mentioned/discussed)• Make figures/tables first, and then insert into the

text• Put the figure/table number beside its title, and put

this in a standard location• Don’t start a sentence with an abbreviation:

Figure vs. Fig.

Acknowledgements

• Keep track of those to be acknowledged-keep a diary so that you don’t forget anyone

• Include: your sponsor, outside sources (companies or agencies), other departments on campus, individuals outside of your team who have helped

• Be brief

References

• Various formats have been developed. Pick one you like such as the IEEE Transactions format

• Decide on a sequence, such as the order they appear in the text

• Always give full references such that others may find the item

References (examples)

• [1] A. Student and A. Professor, “Very Important Project,” in Journal of Irreproducable Research, vol. 13, no. 9, pp. 25-31, Nov. 2004.

• [2] C. Dean, The Book of Earth-Shattering Research, Husky Press, Storrs, CT, 2005.

Plagiarism• Never take the work of others without giving

proper credit• Never take verbatim sentences/paragraphs from the

literature• If you feel that you must use verbatim material,

use quotation marks and a reference. Do this sparingly!

• There are search engines that can find if verbatim material has been stolen.

• Professors fail students who do this. • Additional disciplinary action may follow.

• Create an outline of your report before you write it.

• Write the body of the report first. Then write the front and back matter.

• Have someone proofread your report.

Tips for Writing

References

National Information Standards Organization. Scientific and Technical Reports - Elements, Organization, and Design. ANSI/NISO 239.18-1995 (R1987).

Alley, M. (1996). The craft of scientific writing. (3rd ed.). New York: Springer-Verlag

Day, R. A. (1998). How to write & publish a scientific paper. (5th ed.). CT: The Oryx Press.

Beer, D., McMurrey, D. (2005). A guide to writing as an engineer (2nd ed.). Hoboken, NJ: John Wiley & Sons, Inc.

Lannon, J. M. (1994). Technical writing. NY: Harper Collins College Publishers

Newman, J. M. (2006). Resources for technical and business writing: Glossary. Retrieved August 3, 2006 from http://www.lupinworks.com/roche/pages/glossary.php

References– William Strunk and E. B. White, The Elements of Style

(New York: Macmillian, 2000).– H. R. Fowler, The Little, Brown Handbook (Boston: Little,

Brown and Company, 1980).– G. L. Tuve and L. C. Domholdt, Engineering

Experimentation (New York: McGraw-Hill Book Co., 1966).

– Craig Waddell, Basic Prose Style and Mechanics (Troy, NY: Rensselaer Press, 1990).

– Joseph Williams, Style: Ten Lessons in Clarity and Grace (Glenview, IL: Scott, Foresman, 1981).

– ECE Dept, “Engineering Report Writing,” September 2003.

Documents

Technical Writing