TECHNICAL WRITING
1. 2. 3. 4. 5. 6. 7. 8. 9.
Clarity Conciseness Correctness Style and Tone Figures and Tables Lists Documentation Abstract Proofreading Tips
TECHNICAL WRITING
1. CLARITY Clarity ensures that the reader understands your writing without any difficulty. This means the writing: • Shows a clear grasp of vocabulary, jargon, and standard grammar and punctuation. • Avoids wordiness and obscure words that hide the message. • Follows a logical and predictable organization. Why does this example lack clarity? The office of the Secretary of Defense, Rapid Reaction Technology Office (RRTO), is sponsoring a student design, build, and demonstrate project to explore how effectively motivated, intelligent persons with just a general background in engineering (role filled by undergraduate students), with modest resourcing, and in a relatively short period of time, provide an underwater vehicle capable of locating potential unexploded ordnance (UXO) of discarded sea mines. 2
TECHNICAL WRITING
Now, compare the original with the revised version:
ORIGINAL
REVISED
The office of the Secretary of Defense, Rapid Reaction Technology Office (RRTO), is sponsoring a student design, build, and demonstrate project to explore how effectively motivated, intelligent persons with just a general background in engineering (role filled by undergraduate students), with modest resourcing, and in a relatively short period of time, provide an underwater vehicle capable of locating potential unexploded ordnance (UXO) of discarded sea mines.
The Rapid Reaction Technology Office (RRTO), a subdivision of the Office of the Secretary of Defense, is sponsoring a student design project in order to create an underwater vehicle that explores for unexploded sea mines.
• Subject: RRTO • Verb: is sponsoring • Significance: research to aid in exploring unexploded sea mines.
• Subject: The Rapid Reaction Technology Office • Verb: is sponsoring • Significance: student design project in order to create an underwater vehicle that explores for unexploded sea mines.
The revision reduces the original by half and leaves the reader with a clear understanding of the point.
3
TECHNICAL WRITING
2. CONCISENESS Conciseness means that extraneous words, phrases, clauses, and sentences have been removed without sacrificing clarity or appropriate detail.
Causes of Wordiness: • Redundant Modifiers basic essentials, final outcome, completely finished, present status, red in color Sometimes this is context-specific. • Excessive qualification perfectly clear, completely accurate • Excessive repetition of words and ideas Key difficulties of the project include constraining the broad project scope, designing a system to operate under varying ocean conditions, and designing a system to conform to SOCOM’s mission goals. The system uses several flotation devices along the top of the system to ensure that it will float.
4
TECHNICAL WRITING
• Overuse of pronouns (there, it, who/whom, that, which), often resulting in lengthy, indirect, and unclear expression of ideas There are many web designers who are planning to attend the conference, which is scheduled for May 13-15. While researching options for our project it is important to note how many different ways it is possible to grow plants inside and how one is able to vertically grow plants.
5
TECHNICAL WRITING Here is a list of wordy phrases to avoid: Wordy Phrases Due to the fact that Because of the fact that For all intents and purposes In the process of It seems that For the purpose of In my opinion There are/is and It is At the present time
Replace each with fewer words, or eliminate altogether when possible. For example, revise “due to the fact that” to “because.” All criteria was assumed to be equal weight due to the fact that because this was the team’s first round of conceptual design scoring.
6
TECHNICAL WRITING
3. Correctness Correctness (and a writer’s credibility) revolves around all aspects of a writing project, including use of tables and figures and documentation of source material. Many credibility killers occur with the inaccurate expression of ideas via word choice and grammatical construction. The most common of these include faulty vocabulary, misspellings, and incorrect verb tenses.
Vocabulary and Grammar • Word Choice/Spelling The shoe tying aids and assistive footwear that currently exist are all plaqued by a combination of the previously mentioned problems. • Faulty parallel structure Dysfunction in this system can be seen when a child withdraws when being touched, refuses to wear certain clothing because of its texture and feel, and avoidance of getting their hands dirty.
7
TECHNICAL WRITING • Verb tense Chloramination killed pathogens; however, the reaction is slow. In recent years, Total Organic Carbon (TOC), classified as a non-specific method, is ideal for detecting all carboncontaining compounds …. • Naming/Titles The team has found that this option will defiantly be useful to help recycle water and create a net zero energy building. What is zero net energy? • Capitalization The Frame was invented from singled beamed frame to double beam structure. Others include the iLimb by touch bionics…(it should be ilimb)
8
TECHNICAL WRITING
4. Style and Tone Passive Voice What is passive voice? Active voice emphasizes the actor. Passive voice deemphasizes or obscures the actor.
Active: Werner Heisenberg formulated the uncertainty principle in 1927. Passive: The uncertainty principle was formulated by Werner Heisenberg in 1927. Active: the actor is most important; is stated first Passive: the action or object is most important; actor is stated last‌ or not at all: The uncertainty principle was formulated in 1927.
9
TECHNICAL WRITING Passive voice is generally used to show the following: • The actor is unknown: The cave paintings of Lascaux were made in the Upper Old Stone Age. • The actor is irrelevant: An experimental solar power plant will be built in the Australian desert. • Emphasis is on the person or thing acted on, such as the main topic: Insulin was first discovered in 1921 by researchers at the University of Toronto. It is still the only treatment available for diabetes.
Passive voice is almost always used for business and scientific writing, such as proposals, lab reports, and research papers: • The sodium hydroxide was dissolved in water. This solution was then titrated with hydrochloric acid. In this example, it is clear to the reader that you are the one who did the dissolving and the titrating. The passive voice in this example emphasizes the experiment rather than you.
10
TECHNICAL WRITING
Point of View Third Person Point of View (POV): it, he, she, they
Use third person POV for proposals, academic writing, scientific reports, business reports, and some types of reference books because they require a detached, measured, and impersonal tone. Importantly, use of the third person together with the passive voice keeps focus on the project itself while also creating the sense that the writers and researchers are unbiased.
First or second person POV would be awkward and unprofessional:  First person POV (I, we): use for personal, first-hand accounts  Second person POV (you): use to give instructions
Maintain a consistent point of view throughout the paper: A writer must not shift your point of view.
11
TECHNICAL WRITING
TONE Use a formal, professional, and precise tone. • Vitamix’s “The Quiet One” comes with quite the price tag at a whopping $1,350. With a cost that is slightly out of reach for the standard person, it is not an ideal option. The writers of this example use the language of marketing, not of research and proposals. The word “standard” is simply awkward and inappropriate. • Really, a lot, sort of. These types of phrases and word choices are casual and imprecise.
Use jargon: specialized words appropriate to a certain group or field. You are expected to use the jargon of your discipline. Doing so shows your experience, expertise, and professionalism.
12
TECHNICAL WRITING
5. FIGURES AND TABLES When using figures and tables: • Write clear and informative titles. • Ensure that they are self-explanatory. • Number figures and tables. • Place in the document close to the written reference. • When referencing a table or figure in your text, be accurate in writing the correct table/figure number and title. • If you have more than 5 figures or tables, create a section following the table of contents titled “List of Figures” or “List of Tables.”
13
TECHNICAL WRITING
Figure 1. L-Histidine bound Peptide
As in this example, position the figure number and title at the bottom of the figure.
14
TECHNICAL WRITING
Unlike figures, the number and title of tables must appear at the top of the table, as in the example above.
15
TECHNICAL WRITING
6. LISTS When using bulleted lists: • Write an introductory sentence to explain what the list will contain (such as project specs), followed by a colon. Before we agree to hold the regional sales conference at Brent Hotel, we need to ensure the hotel can provide the following resources: Business center with state-of-the-art digital and printing services Main exhibit area that can accommodate thirty 8foot-by-15-foot booths Wi-Fi internet access and digital projection. • Capitalize the first word in each listed item, unless doing so is visually awkward. • Write the listed items in parallel grammatical structure. • Use periods when the listed items are complete sentences. • Use bullets when you do not wish to indicate rank or sequence. • Use numbers to indicate rank and sequence. • List bulleted items in a logical order, if appropriate. 16
TECHNICAL WRITING
7. DOCUMENTATION In all academic disciplines, you must abide by the ethical code of academic integrity. Among other things, this means that when using outside source material you must document any and all ideas, words, pictures, tables, and figures that are not your own. This includes: • Anything that is not general knowledge; • Any words or ideas taken from another source; • Any facts, statistics, figures or tables that come from someone else’s research; • Anything that has been copy and pasted.
Documentation means creating citations, which have two parts: 1) in-text citation 2) reference page The in-text citation should clearly cross-reference with the entry on the reference page.
17
TECHNICAL WRITING Citations require the following Information, so that anyone can find and confirm the source: • The author(s) who wrote the words. • The page number, if applicable. • Publication information (book or journal, year of publication, name of publishing company, etc.).
What’s wrong with this reference page?
18
TECHNICAL WRITING
8. ABSTRACT An abstract comes at the very beginning of a paper. Generally composed of no more than 250 words, an abstract must include the following information about the project: • • • •
Objectives Importance or value Methodology Results
An approach to hybrid artificial intelligence problem solving is presented in which the aim is to forecast, in real time, the physical parameter values of a complex and dynamic environment: the ocean. In situations in which the rules that determine a system are unknown or fuzzy, the prediction of the parameter values that determine the characteristic behavior of the system can be a problematic task. In such a situation, it has been found that a hybrid artificial intelligence model can provide a more effective means of performing such predictions than either connectionist or symbolic techniques used separately. The hybrid forecasting system that has been developed consists of a case-based reasoning system integrated with a radial basis function artificial neural network. The hybrid problem solving approach provides an effective strategy for forecasting in an environment in which the raw data is derived from three distinct sources: a large database of historical data, satellite image data, and time series data obtained in real-time. Corchado, J.M.; Aiken, J., "Hybrid artificial intelligence methods in oceanographic forecast models," Systems, Man, and Cybernetics, Part C: Applications and Reviews, IEEE Transactions, vol.32, no.4, pp.307,313, Nov. 2002 doi: 10.1109/TSMCC.2002.806072 19
TECHNICAL WRITING
9. PROOFREADING Before submitting your writing to a professor or a supervisor, you must proofread it.
Try the following proven proofreading techniques: • Read your work backwards. • Read your work aloud. • Read the paper one word at a time, uncovering each word as you go. • Always proofread a printed version. • Take time away, return to the paper, and reread with fresh eyes. • Get others involved. • Identify and anticipate the errors you typically make and learn to correct them. • Don’t trust spell check or grammar check.
20
TECHNICAL WRITING
Make an appointment at the Writing & Communications Center for free help with: • writing • public speaking • presentations • resumes and cover letters • interview techniques and preparation • English conversation • and more.
LOCATIONS: • Morton 210 – by appointment and walk-in • Library, Great Hall – walk-in only; first come, first served Find current hours and make an appointment at http://www.stevens.edu/cal/wcc 21