technical writing tips
TRANSCRIPT
1
Technical Writing Advice for Graduate
Students
Laura A. McLay, PhDVirginia Commonwealth UniversityStatistics and Operations Research
© Laura McLay, August 2010
2
OverviewMy talk today has three main topics:1. Avoiding common writing mistakes2. Using figures and tables effectively3. Tips for writing well
My goal is to make writing less painful for you by helping you to avoid common mistakes.
Unless otherwise noted, my tips are for papers and theses.
Note on terminology: Good example refers to something written well. Bad example refers to something that needs to be
revised.
3
Have a beginning, middle, and endYour papers are not a mystery novel. State your main findings
in the1. Abstract2. Introduction, and3. Conclusions
You are not ruining the surprise by stating your conclusions first.
Ask yourself what the main contribution of your paper is. Add this to the introduction of your paper.
Tip: think about having two minutes to “sell” your research to a CEO. What would you say to get the CEO’s attention?
4
Have a beginning, middle, and endEach section/chapter should have a beginning,
middle, and end. Most sections are all middle.
Ask yourself what you set out to accomplish in the section. This is your beginning.
Ask yourself what you are going to do next. This is your end.
5
Topic sentences The first sentence of each paragraph should tell
the reader what the paragraph is about. Topic sentences should make a transition from
the previous paragraph. Start a new paragraph when the topic changes. Avoid one sentence paragraphs.
6
Be precise Be precise with technical terms. This is not the
time to get creative. At first you may feel repetitive and awkward when
writing, but you will get used to it.
Bad Example: Figure 2 shows the system alarm threshold. If more alarms are observed than the threshold, then…
Good example: Bad Example: Figure 2 shows the system alarm threshold. If more alarms are observed than the system alarm threshold, then…
7
Watch verb tense Use present tense.
Gives impression that the reader could replicate results. Makes results appear timeless.
Don’t change tenses. Exception: Use past tense for literature review.
Don’t use future tense Exception: future work.
Good example: Data are generated by sampling a normal distribution ...
Good example: Results are obtained by using such-and-such software...
8
Don’t do “this” Be careful when using "it," "ones", "that,"
"those," etc. Be specific. Rarely use these words.
Bad example: The algorithm is executed 30 times for each scenario. It indicated that…
Good example: The algorithm is executed 30 times for each scenario. The algorithm indicated that…
9
Don’t do “that” Do not start a paragraph with "that" or "it." Don't ask your
reader to go back to a previous paragraph to figure this out. This can be tricky to fix. But in general, don’t use pronouns
and other vague words in the first sentence in a paragraph. Be specific and use absolutes.
Bad example: These issues suggest that using heuristics can be used to provide near-optimal solutions. (which issues???)
Bad example: This method is used to simulate the input data.
Good example: The such-and-such method is used to simulate the input data.
10
Don’t be passive Good writing often uses active (rather than
passive voice). Some passive voice is unavoidable. Blend passive voice with active voice when possible.
Two options for writing:1. Third person (active voice sometimes difficult).
Always use third person when referring to oneself ("the authors", "the investigators")
2. First person using the academic “we” as if the author and reader are considering the subject matter together (active voice is easier—no excuses for writing passively!)
11
Don’t write like you speak Remove colloquial expressions from your writing.
Write more clearly instead. Your writing vocabulary is larger than your
speaking vocabulary. This is OK.
Bad Example: Cat litter triggers security alarms… Good Example: Cat litter signals a security alarms…
Bad Example: The scheduling algorithm operates on the fly…
Good Example: The scheduling algorithm operates in real-time…
12
Don’t write like you speak, continued. I find that students tend to start sentences with a variety of
expressions and clauses. Most of the time, these can be deleted.
Bad Example: So then we removed the variable from the linear model.
Bad Example: The knapsack is greedily packed in order, starting with item 1 until the knapsack is full. For this, the variables are zero or one except for the critical item.
Bad Example: Yielding a primary screening alarm, containers are sent to secondary screening.
Good Example: Containers that yield a primary screening alarm are sent to secondary screening.
13
Don’t write like you speak, continued.Many words and phrases that are in your spoken vocabulary should
never appear in technical writing So,… get put very just of course as you can see in the ballpark dealing with overkill tried and true … Any colloquial expression
There are many, many that I could include here.
14
Say it once Avoid redundancies.
Bad Example: The p-values are also significant as well.
Good Example: The p-values are also significant.
Bad Example: The variables are all zero or one for all items except the critical item.
Good Example: The variables are zero or one for all items except the critical item.
15
Use more commas Students usually use too few commas. Review
the rules. Sometimes omitting a comma is OK, but not in long sentences.
Bad Example: Therefore independence is assumed.
Good Example: Therefore, independence is assumed.
Bad Example: Lions, tigers and bears. Oh my! Good Example: Lions, tigers, and bears. Oh my!
16
More on commas Bad Example: I went to the seminar with Bob, an
officer and a gentleman. Are two or four people going to the seminar?
If Bob is NOT an officer and a gentleman, then you MUST use a comma.
Good Example: I went to the seminar with Bob, an officer, and a gentleman.
If Bob is both an officer and gentleman, then leave as is. But it would be better to clarify.
Good Example: I went to the seminar with Bob. Bob is an officer and a gentleman.
17
Use commas in pairs For dependent clauses, always use commas in
pairs.
Bad Example: The solutions, which are found in less than 60 seconds are also optimal.
Good Example: The solutions, which are found in less than 60 seconds, are also optimal.
18
Which and that Be careful with "which" and "that" and comma
use. Use a comma before "which" and do NOT use a comma before "that."
Good Example: Cargo containers are screened by RPMs, which detect nuclear material.
Good Example: Cargo containers are screened by RPMs that detect nuclear material.
19
Make fewer mistakes Know when to use "less" and "fewer." Use fewer when you are referring to something
you can count (iterations, memory, numbers). Almost always use “fewer!”
Bad Example: The Tabu search algorithm requires 400 less iterations when the long-term memory is set to 50.
Good Example: The Tabu search algorithm requires 400 fewer iterations when the long-term memory is set to 50.
20
Prove it! We can't really prove anything that can't be put in a
Theorem or Proposition, especially with computational or stochastic research.
We can show that things hold in practice, illustrate properties, indicate that something is true for the example considered, suggest that something may be true all the time, or shed light on what might be true in general. But we can't prove the general case when looking at a particular example.
Bad Example: The results for the 48 scenarios prove that our algorithm is robust for solving the model.
Good Example: The results for the 48 scenarios suggest that our algorithm is robust for solving the model.
21
Notes on optimal solutions Know the difference between an “objective
function” (z = cx) and an “objective function value” (145).
Know the difference between a "solution” (x1=12, x2=-1) and a "solution value” (objective function value of 90).
Bad example: All thirty solutions have objectives that are greater than 1.
Good example: All thirty solutions have objective function values that are greater than 1.
22
Not all solutions are optimal An optimal solution is optimal. You will not be
able to find another solution with a better value. If you “solve” an optimization problem, you
guarantee that you found the optimal solution. A heuristic/metaheuristic (like a greedy
algorithm) does not guarantee finding an optimal solution. Don't call the heuristic solution optimal. Heuristic solutions are “near-optimal solutions” or
“approximate solutions.” A heuristic does not “solve” an optimization problem.
Rather, it provides near-optimal solutions.
23
References Be precise with references.
Bad example: Doe et al.’s model resulted in … Good example: The model introduced by Doe et
al. (2007) resulted in …
Record the date when you read something on a web site. You need to provide this in the references.
24
Consistent sentence structure Consistency with verbs Good example: In particular, rural EMS
departments typically operate in larger geographic areas, are not near hospitals, and rely on volunteer staff.
Consistency with propositions Bad example: Cargo containers are screened for
nuclear material, contraband, and by radiation detectors.
Good example: Cargo containers are screened for nuclear material, for contraband, and by radiation detectors.
25
Compare two things, not one thing When comparing two things/methods/etc., always
state what you are comparing to. This is important, because we often compare
things in technical papers and because this is an easy mistake to make.
Bad example: This model provides a more clear and accurate assessment of risk.
Bad example: This model provides a more clear and accurate assessment of risk than the model by Idiot et al. (2004).
26
So happy together Verbs and adverbs go together
Bad example: …decreases the budget requirement significantly.
Bad example: … significantly decreases the budget requirement.
27
Part IINumbers, Figures & Tables
28
Be quantitative. Always. Bad Example: The greedy heuristic gave
solutions that were considerable to the simulated annealing algorithm.
Good example: The greedy heuristic gave solutions whose objective function values were always within one-percent of the solution values to the simulated annealing algorithm.
Bad Example: The p-value is significant in just a few cases.
Good Example: The p-value is significant in 3 of the 50 cases.
29
Number formatting Write large numbers in the form most familiar
with your audience This means scientific notation
2 million or 2M instead of 2,000,000 14,948 instead of 14948 $6.7B (USD) instead of $6.7B 1.2 x 10-4 instead of 0.00012 0.57 instead of .57
30
Spell out numbers Spell out numbers less than twenty
Bad example: First, consider the following 8 scenarios.
Good example: First, consider the following eight scenarios.
There are exceptions: Good example: Consider Case 1… Good example: An upper bound to the optimal solution
value is 1.0.
31
Starting sentences Do not start sentences with a number or a symbol. Sometimes this takes some restructuring.
Bad example: 2,000 test subjects participated in the experiment.
Bad example: As you can see, 2,000 test subjects participated in the experiment.
Good example: A total of 2,000 subjects participated in the experiment.
Bad example: denotes prescreening risk intelligence, which can be found using Bayes rule.
Good example: Bayes rule can be used to find , which denotes prescreening risk intelligence.
32
Significant digits That lesson on significant digits from high school
chemistry is an important lesson.
When you divide 2.34 by 5.55, the answer is .42 (not 0.4216216)
In general, use about two places past the decimal point. Readers don’t want to see 0.4216216, even if it is “significant.”
33
Consistent number structureFrom a NYT article“By comparison, the risk of dying in childbirth is 13
per 100,000 births. The risk of dying from diabetes is 23 per 100,000 population. The risk of dying in a car accident is 1 in 6,700.”
The sentences have a consistent structure. But a better interpretation of the numbers is:
“By comparison, the risk of dying in childbirth is 13 per 100,000 births. The risk of dying from diabetes is 23 per 100,000 population. The risk of dying in a car accident is 15 per 100,000 population.”
34
On equations Each equation should be on its own line and
centered. If it is short, it can be inline with the text. Major equations should be numbered.
Use too few rather than too many equations. Equations are part of the sentence and should be
punctuated accordingly.
Good example:The current in the wire is calculated using
E = IR, (5)where E is current, I is electric potential, and R is resistance.
35
On symbols Define all symbols used, creating a list or table. Define too few rather than too many symbols. Be careful not to duplicate symbols. As with equations, symbols should be
grammatically inserted into sentences.
36
The results section The results section should be built around a few
key figures and tables.
Hint: select the tables and figures before you start writing. You want to tell a good story with tables and figures. This story shouldn't ramble on forever.
Hint: the story you tell is not chronological. Tell the story in an order that it is logical to reader
Hint: there is no correlation between how long something took you to do and how much space it takes in the paper.
37
Figures and Tables Figures and tables often take a lot of time to
format correctly. And then your advisor will ask you to reformat it
because it isn’t clear. Hang in there. If you don't have anything to say about a table or
figure, leave it out. A figure doesn't need to go in your paper just because you spent a lot of time on it.
38
Table tips Make sure the column headings in a table are
clear. Captions go on TOP for tables. The table should fit on a single page. Make sure the caption conveys information
necessary to understand what is in the table. The reader shouldn't have to read the text to understand what is in the table. Exception: sometimes you need to abbreviate terms to
make tables fit on a page. Explain them in the text. Use abbreviations that the user could “guess.”
Significant digits. Don’t use a gazillion.
39
40
Table 12: Probability Mass Functions of Lifetime Risks for False Positives
41
Figures tips Captions go BELOW for figures. Figure should be READABLE. Have a white background and
crisp lines. Should look good when printed in black and white.
Don’t use Excel to make figures. And if you do, do not use default settings.
Make sure axis limits are chosen wisely and are labeled and scaled appropriately. Axis labels sometimes need to be long to be accurate (e.g.,
“The conditional probability that a patient survives given that a patient arrives and is life-threatening”). Define a short term in the text to be used instead so the figure is both accurate and readable (e.g., “Conditional survival probability”)
Include a legend. Figures are not graphs. Never use the term “graphs.”
42
0.00
3.00
6.00
9.00
12.00
20 25 30 35 40 45 55 85
Age (years)
Ave
rag
e S
cree
nin
g A
ge
Incr
ease
1 Screening 2 Screenings 3 Screenings
Figure 15: Average Increase in Optimum Screening Ages as the Duration of Sustained Vaccine Immunity Increases
43
44
Some nice figuresmade with Matlab
1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 60
0.2
0.4
0.6
0.8
1
Initial Stockpile Level (Millions of Doses)
P(S
(tm
)<0)
NT, =0.5
NT, =0.7
NT, =0.9
Exp, =0.5
Exp, =0.7
Exp, =0.9
45
General writing tips Set aside a regular time to write every day. Start
with 30 minutes. Think about what you will write in your next
writing session throughout the day. Developing outlines and jotting notes counts as
writing. Do not feel that you must start writing complete paragraphs beginning with the introduction.
The key to being a good writer is being a good reviser. Read your own work, and read it critically.
46
Technical writing vs. non-technical writingGood technical writing is Technically accurate Useful Concise Complete Clear Consistent Grammatically correct Well-organized Interesting
47
Thesis writing tips Do not write your thesis at the end. Write
throughout your thesis work. The easiest way to write a thesis is to write up each small
project at a time (i.e., a paper submission). Combining the papers into a single thesis takes a couple of weeks. You are more likely to publish your thesis this way.
Give your advisor lots of time to make several revisions. It takes at least two semesters to write a thesis if you don’t write papers along the way.
In addition, it takes at least one semester to revise a thesis after a student gives me their final copy (unless papers are written first).
Use LaTeX! Don’t use Word!! But it’s your prerogative.
48
Final words of warning You will surely read papers and theses that make
the mistakes I’ve warned you about in this presentation. No one is perfect. But that doesn’t justify a lazy or sloppy approach to writing.
Never go to your advisor and say, “In paper XYZ, John Doe uses [colloquial expression]!” to justify your colloquial expressions. Just because someone else makes a mistake, doesn’t mean that you are entitled to make the mistake.
Listen to your advisors! They have published papers, navigated this process, and learned a thing or two about writing.
49
Additional reading The Elements of Style by Strunk and White On Writing Well by William Zinsser. The Elements of Technical Writing by Gary Blake
and Robert W. Bly Scientific poster presentations
http://web.pdx.edu/~clarksk/poster.html
Books I have not read Mathematical Writing by Donald E. Knuth Handbook of Writing for the Mathematical Sciences by Nicholas
J. Higham A Primer of Mathematical Writing by Steven G. Krantz How to Write a Lot: A Practical Guide to Productive Academic
Writing by Paul J. Silvia Writing Your Dissertation in Fifteen Minutes a Day: A Guide to
Starting, Revising, and Finishing Your Doctoral Thesis by Joan Bolker