Presentation on theme: "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."— Presentation 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 confrontational Sirajuddin, David Itcanbeshown.com
Technical Writing Tips 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 graders personal bias. Most people will not allow personal pronouns (I allow it, although I do not prefer it). Sirajuddin, David Itcanbeshown.com
Technical Writing Tips 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) Sirajuddin, David Itcanbeshown.com
Technical Writing Tips 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 ! Sirajuddin, David Itcanbeshown.com
Technical Writing Tips Structure: See Appendix A in [Plesha, Costanzo, Gray] Whether or not you have sections is your own choice. Most journals demand their articles be sectioned (e.g. Phys. Fluids) Some journals demand there be no sections (e.g. Phys. Rev. Letters) Most classes will want you to have them (I do not mind though). Design Project Suggested Format Sirajuddin, David Itcanbeshown.com Discussion Subsections Conclusions References/Bibliography Appendix Abstract Introduction Design Subsections Results Subsections
Technical Writing Tips Design project suggested format: Abstract Sirajuddin, David Itcanbeshown.com If you include an abstract, it is separate from your report. An abstract contains A complete summary of the important details of your (with numerical values!) Do not refer the reader to figures, tables here 
Technical Writing Tips Design project suggested format: Design Subsections Results Subsections Discussion Subsections Sirajuddin, David Itcanbeshown.com Provide your design, give all relevant parameters Summarize results in Only talk about general methods of solving the problem, this is a presentation of your results, appendix shows calculations you must mention assumptions (e.g. static analysis) Figures Tables N.B. You must have a figure showing the scenario somewhere here, or in the intro (not in the appendix)
Technical Writing Tips Tables and Figures Must have captions! Include a citation if you used someone elses figure with square brackets  Sirajuddin, David Itcanbeshown.com Notice citations! Here,  corresponds to [Plesha] from the references section of  If you alter a figure, you still have to cite it, write as [Adapted from #]
Technical Writing Tips Design project suggested format: Conclusions Sirajuddin, David Itcanbeshown.com 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!
Technical Writing Tips Design project suggested format: References/Bibliography Sirajuddin, David Itcanbeshown.com MUST list references Alphabetized
Technical Writing Tips 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 . 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 Brownings 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]. Sirajuddin, David Itcanbeshown.com
Technical Writing Tips Design project suggested format: Appendix Sirajuddin, David Itcanbeshown.com 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  Sirajuddin, David. Design of Cabling for an Overhead Camera for Camp Randall Stadium. October 15, Date Accessed: November 16, Sirajuddin, David Itcanbeshown.com