Скачать презентацию Professional Development CSCE 488 Technical Writing for Computer Скачать презентацию Professional Development CSCE 488 Technical Writing for Computer

4a39c52c92a59646c3e8633873d68291.ppt

  • Количество слайдов: 42

Professional Development CSCE 488 Technical Writing for Computer Engineers (Adapted from material developed by Professional Development CSCE 488 Technical Writing for Computer Engineers (Adapted from material developed by Roger Kieckhafer & Sharad Seth) [Gol 96, Sch 99] 8/29/2001 CSCE 488: Technical Writing

Lecture Overview l Introduction and Motivation l General Tips on Default Style l Tips Lecture Overview l Introduction and Motivation l General Tips on Default Style l Tips on Individual Parts of the Paper Abstract F Introduction F Main Body F Figures and Tables F Appendices F References and Citations F l Tips on Prose Style l References List 8/29/2001 CSCE 488: Technical Writing 2

Purpose of Technical Writing l Present a new idea, product or result F F Purpose of Technical Writing l Present a new idea, product or result F F l to an audience that can make use of it in a level of detail appropriate for that audience Types of results F Algorithm F System component (hardware, software, protocol) F Performance eval. (analytical, simulated, measured) F Theoretical framework (theorems, lemmas, etc) F System model (way of looking at an object) 8/29/2001 CSCE 488: Technical Writing 3

Many Types of Technical Documents l Journal Article or Conference Paper F F l Many Types of Technical Documents l Journal Article or Conference Paper F F l Tends to be very formal and precise style (3 rd person) Novelty of results is of interest to a large audience Review Papers/Tutorials F F l Like above Synthesize existing results for researchers or students Technical Report F F l Often precedes formal publication; also formal and precise Results may be of interest only “in-house” Grant Proposal F More proactive, positive style (1 st person) F Must “sell” the idea on its technical merits 8/29/2001 CSCE 488: Technical Writing 4

Technical Content l Statement of the problem F F l explain the significance of Technical Content l Statement of the problem F F l explain the significance of the problem give a level of detail appropriate to the audience Background and previous work F F l demonstrate that you understand the state-of-the-art ensure the reader understands the state-of-the-art Your approach to the problem F in sufficient detail to establish its validity F what is new or different about your approach? 8/29/2001 CSCE 488: Technical Writing 5

Technical Content l Statement of your results F F What is the significance of Technical Content l Statement of your results F F What is the significance of the results? F How do these results compare to previous results? F l What is new or different? Stick to the facts (this is not a commercial) Future work F Where can we go from here? F What new avenues, questions, approaches have been opened up by this work? 8/29/2001 CSCE 488: Technical Writing 6

Typical Paper Outline l Abstract l Introduction (Section 1) l Main Body of the Typical Paper Outline l Abstract l Introduction (Section 1) l Main Body of the paper (Sections 2, 3, . . . ) F background F approach and results F conclusions and future work l Acknowledgements (a few, if appropriate) l References l Appendices (if needed) 8/29/2001 CSCE 488: Technical Writing 7

General Advice l Read the pub’s instructions to authors (!!!) F Also, look at General Advice l Read the pub’s instructions to authors (!!!) F Also, look at recent issues of the target pub. F incorrect style may it is rejected without being read Q especially Q no l true for grants & more competitive pubs reviewer wants to read single-spaced 10 -pt. font Visual Presentation F should be clear, clean, professional F Company Logo and nice formatting is O. K. F avoid “cutsy”, “artsy”, or overly distracting cosmetics 8/29/2001 CSCE 488: Technical Writing 8

Default Style (unless otherwise directed) l 8. 5 x 11 inch or A 4 Default Style (unless otherwise directed) l 8. 5 x 11 inch or A 4 paper F If single-sided, no garbage on the back side F Double-sided OK to conserve paper l One inch margins all around l Single-column format l Professional looking font F e. g. Times New Roman or La. Te. X rm font F 12 -point for normal text F Dark, black, letter quality print (no dot matrix) 8/29/2001 CSCE 488: Technical Writing 9

Default Style (unless otherwise directed) l Double-space or 1. 5 -space F F l Default Style (unless otherwise directed) l Double-space or 1. 5 -space F F l much easier to read allows room for reviewers’ comments Paragraphs F F Leave a blank line between paragraphs F l Use some! Indenting the 1 st line is optional Bind only in a 3 -ring binder F 8/29/2001 On-line submission even better CSCE 488: Technical Writing 10

Default Style (unless otherwise directed) l Numbering pages, figures, tables F all numbers must Default Style (unless otherwise directed) l Numbering pages, figures, tables F all numbers must be globally unique F all must be in lexicographically increasing order, e. g. Q 1, 2, 3, 4 Q I-1, l I-2, I-3, … II-1, II-2, II-3 (for very long reports) Numbering Chapters, Sections, Subsections F must be globally unique and hierarchical, e. g. 1. 3 Gnus and Gnats 1. 3. 1 Gnus 1. 3. 2 Gnats 8/29/2001 I. C Gnus and Gnats I. C. a Gnus I. C. b Gnats CSCE 488: Technical Writing 11

Abstract l Must be clear and concise (typ. 50 - 200 words) F F Abstract l Must be clear and concise (typ. 50 - 200 words) F F l Reader must be able to quickly identify content Helps reader decide whether to read the paper Briefly summarize F F significance F approach F l problem results Do not cite references (abstract may be published alone) 8/29/2001 CSCE 488: Technical Writing 12

Introduction l Let the reader know what the paper is about F Define and Introduction l Let the reader know what the paper is about F Define and motivate the problem F Overview limitations of state-of-the-art F Overview your approach F Overview your results l Get to the point quickly l Know your audience l Do not refer to or depend on the Abstract l Final paragraph should outline organization of paper 8/29/2001 CSCE 488: Technical Writing 13

Main Body l Background F F l expand on problem statement explain state-of-the-art and Main Body l Background F F l expand on problem statement explain state-of-the-art and its limitations Approach F describe in sufficient detail for the audience F clearly state applicability and limitations F compare to state-of-the-art, if appropriate Q Highlight F 8/29/2001 the differences examples can help a lot CSCE 488: Technical Writing 14

Main Body l Results F clearly state what they are F clearly compare to Main Body l Results F clearly state what they are F clearly compare to other benchmarks, e. g. Q state-of-the-art Q optimal Q naïve F alternatives solutions (if known) solutions (e. g. random guessing) clearly state your comparison criteria, e. g. Q accuracy Q complexity or time Q cost 8/29/2001 CSCE 488: Technical Writing 15

Main Body l Conclusions and future work F drive the results home clearly and Main Body l Conclusions and future work F drive the results home clearly and concisely Q restate your main results Q restate their significance F a reviewer or reader may start by reading the Introduction and Conclusions first F Clearly state where we can go from here Q shows Q invites 8/29/2001 the work has a future participation from the readers CSCE 488: Technical Writing 16

Figures and Tables l Try to embed figures and tables in the main text Figures and Tables l Try to embed figures and tables in the main text F l Use graphical software if at all possible F l if necessary, insert special section after “References” use hand-drawn figures only as a last resort Must be numbered & referred to by number in the text F F l Locate figure after paragraph containing 1 st reference Do not refer to “the following figure” (they may move) All figures and tables need a short numbered caption, F e. g. , “Figure 1: 1998 Gnu-to-Gnat Population Ratios” F Generally located under a figure but above a table 8/29/2001 CSCE 488: Technical Writing 17

Figures and Tables l All objects and fonts must be clearly readable F F Figures and Tables l All objects and fonts must be clearly readable F F l if a figure is too big, break it into smaller figures add a figure to hierarchically decompose it All must be accompanied by explanatory text F F clearly state the results you want the reader to see F l walk the reader through the figure or table clearly state the relationships between related figures Know what you want each figure to illustrate F one good figure really is worth a thousand words F a thousand bad figures are worth nothing 8/29/2001 CSCE 488: Technical Writing 18

Appendices l Use for long complex data of peripheral interest F Data that would Appendices l Use for long complex data of peripheral interest F Data that would disrupt the flow of the main text, F Data the “casual” reader does not need, e. g. Q Huge figures Q Large tables of raw data Q Complete source code listings l Limit each appendix to 1 major topic l Each must be lettered, and cited in the text by letter l Remember, page numbers must be globally unique 8/29/2001 CSCE 488: Technical Writing 19

References and Citations l References are listed in the References section F F l References and Citations l References are listed in the References section F F l Do not use footnotes for references Footnotes are used for parenthetical comments Options for order of the reference list: F F l Alphabetical by last name of first author In order of citation in the paper Must have a consistent mapping F All references in the list must be cited in the text F All references cited in the text must be listed 8/29/2001 CSCE 488: Technical Writing 20

Referencing Papers and Articles l Format: F Authors in-order (1 st-init. Lastname), Q do Referencing Papers and Articles l Format: F Authors in-order (1 st-init. Lastname), Q do not use “et al. ” (unless > 5 authors) F “Title of Article” in quotes (this can vary), F Title of Journal or Conference in Italics, Q Do not excessively abbreviate F Journal volume & number, F Article page numbers, F Month & year. 8/29/2001 CSCE 488: Technical Writing 21

Referencing Papers and Articles l Examples: F F l F. J. Meyer, D. K. Referencing Papers and Articles l Examples: F F l F. J. Meyer, D. K. Pradhan, “Consensus with Dual Failure Modes”, Proc. 17 th Fault-Tolerant Computing Symp. (FTCS-17), pp. 48 -54, Jul. 1987. C. M. Krishna, K. G. Shin, R. W. Butler, “Ensuring Fault -Tolerance of Phase-Locked Clocks”, IEEE Trans. Computers, V. C-34, No. 8, pp. 752 -756, Aug. 1985. Notes: F all fields separated by commas F entry terminated by period F “and” before final author seems to be optional 8/29/2001 CSCE 488: Technical Writing 22

Referencing Books l Format: F Authors in-order (use the data they use), Q do Referencing Books l Format: F Authors in-order (use the data they use), Q do F not use “et al. ” (unless > 5 authors) Title of Book, and Edition in Italics, Q Do not abbreviate F Location: F Publisher, F year of cited edition, F page numbers (if a specific citation). 8/29/2001 CSCE 488: Technical Writing 23

Referencing Books l Example: F l William Stallings, Computer Organization and Architecture: designing for Referencing Books l Example: F l William Stallings, Computer Organization and Architecture: designing for Performance, 5 th Ed. , Upper Saddle Hill, NJ: Prentice Hall, 1999, pp. 349357. Notes: F “location: ” is often omitted, F Companies and government agencies often omit names of authors Q In 8/29/2001 that case list the company or agency as author CSCE 488: Technical Writing 24

Referencing Web Sites l Format: F There is no agreed-upon format. F Recommendation: Q Referencing Web Sites l Format: F There is no agreed-upon format. F Recommendation: Q Authors Q Title if known in italics, Q Modified: Date/time, (In Netscape click: View Page Info) Q 8/29/2001 Complete URL (including protocol) CSCE 488: Technical Writing 25

Referencing Web Sites l Example F l Henning Schulzrinne, Checklist for Articles, http: //www. Referencing Web Sites l Example F l Henning Schulzrinne, Checklist for Articles, http: //www. cs. columbia. edu/~hgs/etc/writing-style. html Modified: Dec. 22, 1999, 1: 59: 40 PM, GMT. Notes: F Web pages are considered weak references because Q They Q Their F 8/29/2001 have not survived peer review and editing contents are very volatile If you got a published paper or book from the web, then list it as a paper or book, although you may append “available at: full-URL”. CSCE 488: Technical Writing 26

Citation Styles l Numbered Citations (e. g. IEEE Transactions) F The reference list must Citation Styles l Numbered Citations (e. g. IEEE Transactions) F The reference list must be numbered F All citations refer to the reference by number Q may F add more detail if needed Citation may be square-bracketed [1] or superscript 1 Q brackets F are preferred by IEEE Examples: Q… Q… 8/29/2001 has already been proven [12]. has already been demonstrated [12, Fig. 4]. CSCE 488: Technical Writing 27

Citation Styles l Full Last Names (APA Style) F All citations list in parentheses: Citation Styles l Full Last Names (APA Style) F All citations list in parentheses: Q Authors, Q year. F Use et al. If there are 3 or more authors F Examples: Q… already been proven (Smith and Jones, 1999). Q… already been demonstrated (Jagger et al. , 1967, Fig. 4). 8/29/2001 CSCE 488: Technical Writing 28

Citation Styles l Abbreviated name (some conferences, less popular) F Concatenate in square brackets Citation Styles l Abbreviated name (some conferences, less popular) F Concatenate in square brackets Q 1 st Q last F 3 letters of primary author, 2 digits of year. Examples: Q… Q… F has already been proven [Smi 99] has already been demonstrated [Jag 67, Fig. 4]. If author has more than one pub/year, append a letter Q [Jag 67], 8/29/2001 [Jag 67 a], [Jag 67 b] CSCE 488: Technical Writing 29

Citation Advice l Citation is less disruptive to flow at end of sentence, F Citation Advice l Citation is less disruptive to flow at end of sentence, F l However, that location may alter the interpretation Don’t use a citation as a noun, e. g. F BAD: … been proven in [12]. F GOOD: … been proven by Smith and Jones [12]. l List Multiple citations in same brackets, e. g. [1, 2, 5] l Cite the source of a figure or table in the caption, e. g. F 8/29/2001 Table 1: Gnu vs. Gnat Basketball Scores [12, Table 3]. CSCE 488: Technical Writing 30

Plagiarism l The use of someone else’s “intellectual property” without proper citation of the Plagiarism l The use of someone else’s “intellectual property” without proper citation of the source. l Includes: F F Ideas: concepts, definitions, observations, results, data, facts, claims, recommendations, etc. F l Text: direct quotes or very close paraphrasing Figures or Tables: even if you redraw them When in doubt, cite the source! 8/29/2001 CSCE 488: Technical Writing 31

Prose Style l Generally use third person F Draws attention to the topic, not Prose Style l Generally use third person F Draws attention to the topic, not the author F Passive voice is quite common, Q e. g. “the intermediate results are then passed from the ALU to the register bank” Q heavy F use of forms of “to be” flags passive voice Active voice can be clearer and shorter Q e. g. The ALU then passes the intermediate results to the register bank” Q Just 8/29/2001 beware of anthropromorphizations CSCE 488: Technical Writing 32

Prose Style l Use the First Person to identify your contributions Q “A gnus Prose Style l Use the First Person to identify your contributions Q “A gnus is defined as…” leaves doubt Q “We l define a gnu as…” leaves no doubt Generally Avoid Explicit Second Person: F Readers don’t like being given orders. F Exceptions: Q Paper navigation: “Recall from Subsection 3. 3…” Q Tutorials 8/29/2001 CSCE 488: Technical Writing 33

Prose Style l Use consistent verb tense F Present tense = default F Past Prose Style l Use consistent verb tense F Present tense = default F Past tense: Q referring to previous work Q backwards F Future tense: Q Forward l references in the paper, references in the paper Do not use contractions in formal writing 8/29/2001 CSCE 488: Technical Writing 34

Prose Style l When used in-line, numbers 10 are spelled out l Avoid excessive Prose Style l When used in-line, numbers 10 are spelled out l Avoid excessive mathematics in-line l Equations need some explanatory text l Always define an abbreviation at its first use F e. g. “… the Command Control Bus (CCB) …” F exceptions: universal terms (RAM, ROM, CPU) Q Again, F 8/29/2001 know your audience (e. g. ATM) If you have not used a term for several pages, then redefine it when it is reintroduced. CSCE 488: Technical Writing 35

Prose Style l Be absolutely consistent with important terms l Use variation in the Prose Style l Be absolutely consistent with important terms l Use variation in the little grammatical stuff, e. g. F l Be careful with pronouns, F l “e. g. , ” = “for example” = “such as” their meaning can get lost easily Pay attention to your sentence structures F Short clear sentences = good, F Long convoluted sentences = bad, F Incomplete sentences = worse. 8/29/2001 CSCE 488: Technical Writing 36

Prose Style l Use parenthetical remarks sparingly (as they tend to interrupt the flow Prose Style l Use parenthetical remarks sparingly (as they tend to interrupt the flow of the sentence) F F l keep them short, find the least disruptive place to put them in the sentence, Use footnotes for longer supplementary remarks, F Less disruptive than a parenthetical remark F Still, use footnotes sparingly Q no 8/29/2001 more than 1 or 2 on a given page more than a handful in the whole paper CSCE 488: Technical Writing 37

Budgeting Your Time l Time allocation for a 15 -page paper F I don’t Budgeting Your Time l Time allocation for a 15 -page paper F I don’t know who originated these numbers F But they are pretty accurate F Note: Don’t scrimp on the “outline” time 8/29/2001 CSCE 488: Technical Writing 38

Closing Comments l When in doubt, follow publisher’s instructions l When in doubt, cite Closing Comments l When in doubt, follow publisher’s instructions l When in doubt, cite the source l Spelling and Grammar checkers: F l Use them, but don’t trust them implicitly Outside proofreaders: F F l use one pick one whose English is better than yours Remember, the reviewer doesn’t really want to read this paper. Don’t give him/her an excuse to quit. 8/29/2001 CSCE 488: Technical Writing 39

Blank 8/29/2001 CSCE 488: Technical Writing 40 Blank 8/29/2001 CSCE 488: Technical Writing 40

References l [Gol 96] O. Goldreich, How not to write a paper, unpublished, Dec. References l [Gol 96] O. Goldreich, How not to write a paper, unpublished, Dec. 21, 1996, available at: http: //www. wisdom. weizmann. ac. il/home/oded/ public_html/writing. html. l [IEE 97] IEEE, Information for IEEE Transactions, Journals, and Letters Authors, 1997, available at: http: //www. ieee. org/ organizations/pubs/transactions/information. htm l [IEE 99] IEEE-CS, CS Style-Guide - References http: //www. computer. org/author/style/refer. htm Modified: Dec. 06, 1999 9: 24: 10 PM GMT 8/29/2001 CSCE 488: Technical Writing 41

References l [Sch 99] Henning Schulzrinne, Checklist for Articles, http: //www. cs. columbia. edu/~hgs/etc/writing-style. References l [Sch 99] Henning Schulzrinne, Checklist for Articles, http: //www. cs. columbia. edu/~hgs/etc/writing-style. html Modified: Dec. 22, 1999, 1: 59: 40 PM, GMT. l [Str 79] William Strunk Jr. , and E. B. White, The Elements of Style, 3 rd Ed. , New York: Allyn & Bacon, 1995. 8/29/2001 CSCE 488: Technical Writing 42