Presentation is loading. Please wait.

Presentation is loading. Please wait.

Technical Writing Tips

Similar presentations


Presentation on theme: "Technical Writing Tips"— Presentation transcript:

1 Technical Writing Tips
3/25/ :34 AM 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 Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 1

2 Technical Writing Tips
3/25/ :34 AM 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). Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 2

3 Technical Writing Tips
3/25/ :34 AM 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) Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 3

4 Technical Writing Tips
3/25/ :34 AM Never start a sentence with a parameter name (e.g. “q was determined to be…”) Instead, use fillers: “The angle q between the steel bar AB and the vertical was determined to be…” “The angle q was determined to be…” “The parameter q was determined to be…” “The quantity q 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, q, was determined to be…” To the not careful reader, this makes it seem like the vertical is labeled as q! Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 4

5 Technical Writing Tips
3/25/ :34 AM 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 Abstract Introduction Design Subsections Results Discussion Subsections Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 5

6 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract Introduction Design Subsections Results Discussion Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 6

7 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract 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 [1] Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 7

8 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract Introduction Design Subsections Results Discussion Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 8

9 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Introduction This is like a “less-detailed” abstract, should provide Motivation Set up the problem [1] Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 9

10 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract Introduction Design Subsections Results Discussion Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 10

11 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Design Subsections Results Discussion 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) Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 11

12 Technical Writing Tips
3/25/ :34 AM 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 #] Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 12

13 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract Introduction Design Subsections Results Discussion Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 13

14 Technical Writing Tips
3/25/ :34 AM Design project suggested format: 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! Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 14

15 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract Introduction Design Subsections Results Discussion Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 15

16 Technical Writing Tips
3/25/ :34 AM Design project suggested format: References/Bibliography MUST list references Alphabetized Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 16

17 Technical Writing Tips
3/25/ :34 AM 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].” Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 17

18 Technical Writing Tips
3/25/ :34 AM Design project suggested format: Abstract Introduction Design Subsections Results Discussion Conclusions References/Bibliography Appendix Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 18

19 Technical Writing Tips
3/25/ :34 AM Design project suggested format: 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. Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 19

20 References 3/25/ :34 AM [1] Sirajuddin, David. Design of Cabling for an Overhead Camera for Camp Randall Stadium. October 15, Date Accessed: November 16, < Design_of_Cabling_for_an_Overhead_Camera.pdf > Itcanbeshown.com Sirajuddin, David © 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. 20


Download ppt "Technical Writing Tips"

Similar presentations


Ads by Google