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

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

confrontationalSirajuddin, DavidSirajuddin, DavidItcanbeshown.comItcanbeshown.com


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).

Sirajuddin, DavidSirajuddin, DavidItcanbeshown.comItcanbeshown.com


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

!



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


Discussion Subsections

Conclusions References/Bibliography Appendix

Abstract Introduction Design

Subsections Results

Subsections


Design project suggested format:


Subsections Results

Subsections Discussion

Subsections Conclusions References/Bibliography Appendix




Abstract


If you include an abstract, it is “separate” from your report. An abstract containsA complete summary of the important

details of your (with numerical values!) Do not refer the reader to figures, tables here

[1]

“

”




Subsections Results






Introduction


This is like a “less-detailed” abstract, should provide Motivation

Set up the problem

“

”[1]




Subsections Results






Design Subsections

Results Subsections

Discussion Subsections


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)


Tables and Figures Must have captions! Include a citation if you used someone

else’s figure with square brackets []


Notice citations! Here, [3] corresponds to [Plesha] from the references section of [1]

If you alter a figure, you still have to cite it, write as [Adapted from #]




Subsections Results






Conclusions


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!




Subsections Results






References/Bibliography


MUST list references Alphabetized


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].”





Subsections Results






Appendix


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 >


Documents

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