Technical Writing Tips See Appendix A in [Plesha, Costanzo, Gray] for a guide General writing pro tips: Everything should be in past tense (as you already did the analysis), unless you are referencing a figure/table (e.g. “The scenario is shown in Figure 1.”), not talking about your design (e.g. introduction), or in summary (if desired) With that criterion, where we proceed next gets into a classic disagreement (using personal pronouns vs. passive voice) Personal Pronouns : only use “we” (even if you are the only person in a group). Pronouns are generally discouraged in scientific writings, but accepted by many Never mention the reader (second person, “you”) Never mention yourself (first person, “I”) The inclusionary “we” provides a perceived humility, is more professional, and less confrontational Sirajuddin, David Sirajuddin, David Itcanbeshown.com Itcanbeshown.com
20
Embed
Technical Writing Tips See Appendix A in [Plesha, Costanzo, Gray] for a guide General writing pro tips: Everything should be in past tense (as you already.
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Technical Writing Tips
See Appendix A in [Plesha, Costanzo, Gray] for a guide
General writing pro tips: Everything should be in past tense (as you already did the
analysis), unless you are referencing a figure/table (e.g. “The scenario is shown in Figure 1.”), not talking about your design (e.g. introduction), or in summary (if desired) With that criterion, where we proceed next gets into a classic
disagreement (using personal pronouns vs. passive voice) Personal Pronouns: only use “we” (even if you are the only
person in a group). Pronouns are generally discouraged in scientific writings, but accepted
by many Never mention the reader (second person, “you”) Never mention yourself (first person, “I”) The inclusionary “we” provides a perceived humility, is more professional, and less
However, most writing is done without personal pronouns, i.e. passive voice
Passive Voice: extant (‘to be’) + past participle (-ed verb form) “the passive voice should be used when the receiver of the action is more
important than the doer, or when the doer is unknown, unimportant, or perhaps too obvious to be worth mentioning “ [Merriam-Webster]
E.g. Do NOT write “I determined the hoist can sustain a 4000 lb maximum load,”
SHOULD write: “The hoist was determined to sustain a 4000 lb maximum load.”
In the above example, the ‘hoist’ is the emphasis. Including the subject ‘I’ (or even “we”) distracts the reader.
Grammar: the passive voice eliminates the grammatical actor, and converts the object into the subject.
Bottom line: how your technical writing is graded is subject to the grader’s personal bias. Most people will not allow personal pronouns (I allow it, although I do not prefer it).
Be concise Explain everything (do not mention random parameter names
without first defining them) Be very descriptive with your language, especially when describing
the scenario. Reread it to make sure the words themselves completely describe the problem.
Page limits mean words + figures + tables Do not go over, your writing will be better if you can rephrase it to be
more succinct anyway (this takes a significant amount of work sometimes) Real scientific journals have page limits they strictly adhere to 2 pages is more than enough, compact your results into tables, use
figures, etc. Make the figures/tables an appropriate size
In the end: a technically competent person (e.g. friend) who is not in the class should be able to read your report, and understand it. (This especially means, make sure to tell the reader you are doing static analysis, there is no reason why anyone would assume you were in a lot of problems)
Never start a sentence with a parameter name (e.g. “ was determined to be…”)
Instead, use fillers: “The angle between the steel bar AB and the vertical was determined to
be…” “The angle was determined to be…” “The parameter was determined to be…” “The quantity was determined to be…” All of the above are fine, despite the last two examples vagueness, it is
common.
Notice how the first sentence could be confusing if you were to write: “The angle between the steel bar AB and the vertical, , was determined
to be…” To the not careful reader, this makes it seem like the vertical is labeled as
This is a “more-detailed” abstract Summarize your design (with values) Tie it into the introduction (motivation) Summarize deficiencies, future prospects, how to resolve any issues, etc. Do not use the same wording you used in the abstract!
Different ways of citing Usually square brackets [] are used, some texts (e.g. Knoll,
Radiation Detection and Measurement) use paranthesis.
Suppose we have 8 references in our bibliography that are numbered.
We can cite in a number of ways:
“Recent investigators [2, 7] have presented numerical evidence that contradicts the long accepted theory of relaxation in a driven spheromak plasma [5].”
“Recent investigators (Refs. 2, 7) have presented numerical evidence that contradicts the long accepted theory of relaxation in a driven spheromak plasma (Ref. 5).”
“Recent investigators [Boozer, Tang] have presented numerical evidence that contradicts the long accepted theory of relaxation in a driven spheromak plasma [Kitson, et. al].”
And, so on…
If there is only one thing to cite in a sentence, put the citation at the end.
“While Kitson and Browning’s linearized work demonstrated that the allowed equilibrium states in a relaxed plasma are restricted by resonances, numerical work at Los Alamos National Lab has shown that a nonlinear treatment regularizes the resonances creating additional allowed equilibrium states [2, 7].”
Appendix is “separate” In the main report, do not refer to crucial figures in the appendix. However, still refer the reader to the appendix at some point, elsewise it is kind of random to just have an appendix in a report.
References
[1] Sirajuddin, David. Design of Cabling for an Overhead Camera for Camp Randall Stadium. October 15, 2009. Date Accessed: November 16, 2009. < http://www.itcanbeshown.com/For_Students/ Design_of_Cabling_for_an_Overhead_Camera.pdf >