Technical Writing
description
Transcript of 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
Rhetoric HOW WRITING WORKS
BA
Consider this example:
if you wanted to slide a box across a floor to a specific spot . . .
Rhetoric HOW WRITING WORKS
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 . . .
Rhetoric HOW WRITING WORKS
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?
Rhetoric HOW WRITING WORKS
What is the message?
What data / evidence is necessary to support this purpose?
What is the purpose of writing?
Rhetoric HOW WRITING WORKS
• Inform• Persuade• Motivate
What does the text say about the writer?
Rhetoric HOW WRITING WORKS
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?
Rhetoric HOW WRITING WORKS
Who is the writer?
• Mechanical errors?• Inconsistent tense• Uneven or inappropriate tone?• 1st or 2nd person (versus 3rd person)?
Rhetoric HOW WRITING WORKS
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
COMPONENTS OF A TECHNICAL REPORT
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
COMPONENTS OF A TECHNICAL REPORT
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
COMPONENTS OF A TECHNICAL REPORT
Introduction
Introduction:
What goes into it?
Report Format
COMPONENTS OF A TECHNICAL REPORT
• 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
COMPONENTS OF A TECHNICAL REPORT
Set up contextDefine scope
Foreshowing / mapping
State problem/thesis/question
Introduction:
What goes into it?
Report Format
COMPONENTS OF A TECHNICAL REPORT
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 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 for cognition,,
Repetition is necessary for cognition, Repetition is necessary for cognition,
Repetition is necessary ,
Repetition is necessary Repetition is necessary for cognition,
Repetition is necessary for cognition, 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
COMPONENTS OF A TECHNICAL REPORT
Conclusions
Summarize Key points
State Conclusion
State Relevance
Give recommendations for further actions
Report Format
COMPONENTS OF A TECHNICAL REPORT
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, 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 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 for cognition
Report Format
COMPONENTS OF A TECHNICAL REPORT
Summarize key points
Body
Report Format
COMPONENTS OF A TECHNICAL REPORT
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
COMPONENTS OF A TECHNICAL REPORT
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
COMPONENTS OF A TECHNICAL REPORT
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
COMPONENTS OF A TECHNICAL REPORT
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*
*May be an optional element
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.
*May be an optional element
Front Matter: List of Figures and Tables*
iv
Front Matter: List of Figures and Tables*
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.
*May be an optional element
Front Matter: List of Figures and Tables*
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.
*May be an optional element
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
*May be an optional element
•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.
*May be an optional element
Text: Recommendations*
*May be an optional element
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
*May be an optional element
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
*May be an optional element
Back Matter: Appendixes*
*May be an optional element
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.
*May be an optional element
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.