Writing Technical Stuff

1. Cindy Norris Writing Technical Stuff

2. The Stuff • CS MS/PhD thesis • CS conference paper or journal article • CS literature survey • CS grant proposal or thesis proposal These may have different organizations but the style of writing is the same

3. A little about Style • Clear communication – • Not ambiguous – 9 instead of small • Don’t use fancy words – you are a scientist, not a poet • Don’t inject your opinions – you are a scientist, not an editorialist • Write in a formal, but not artificial, style

4. How to get Started • Create an outline • Come up with an outline that includes chapters, sections and subsections • For each subsection, come up with the topic sentence for every paragraph that will appear in the subsection • If you can’t express the point of the paragraph in one sentence, you probably need more than one paragraph • After you’ve written all topic sentences for the subsection, now you are ready to write the actual paragraph • Save abstract for the end – usually the easiest thing to write is the “meat”

5. The Basics • The next slides go through lots of problems I’ve found when reading the technical writing of students • For a more comprehensive list, grab a book

6. Avoid pronouns • Don’t use our, we, my, etc. If a pronoun absolutely must be used, then use we or our (even if you are referring to work you performed alone)‏ • Instead of: My experiments … Have: Our experiments …

7. Active voice instead of passive • Active is more direct, bold and concise • Active voice – subject performs the action expressed by the verb • Scientists conducted research. • Passive voice – subject receives the action expressed by the verb • Research was conducted by scientists. • However, sometimes we use passive in scientific writing to be able to omit a pronoun and this is preferable to using the pronoun

8. Present tense • Write conference, journal papers, theses in present tense • Summary can be in past tense • Body of paper: This paper presents … • Summary : This paper presented…

9. Where to put citations • Place immediately after introducing the topic: • Virtual memory [1, 2, 3] is a technique • Or place at the end of the sentence: • Virtual memory is a technique … main memory [1, 2, 3]. • Don’t have the same set of cites throughout a section; once in the first paragraph is sufficient • Don’t have items in the bibliography which are not cited within the text or vice-versa

10. How to cite • Cite either by number • Body of paper: Fenwick [2] proposes a technique for … • Bibliography entry: [2] James B. Fenwick, Jr. Name of Paper. Name of Conference, 2006. • Or, cite by name and date. If there is more than one paper by that author in that year, append year with a letter • Body of paper: Fenwick (Fenwick, 2006a) proposes a technique for … • Bibliography: (Fenwick, 2006a) James B. Fenwick, Jr. Name of Paper. Name of Conference, 2006.

11. Figures • Should appear on the same page as mentioned or on the page immediately after • Figures must be discussed within the text

12. Sentences • Not too long – difficult to follow a long sentence in a technical paper • Not too short – sounds choppy • Just right!

13. Cohesion • Each paragraph should flow nicely into the next paragraph • Each sentence should flow nicely into the next sentence • Sometimes linking words or phrases are needed to achieve a smooth flow between sentences • In particular, furthermore, in addition, consequently, although, however, ..

14. Spelling • Use a spell checker and proof read your papers! • Enough said.

15. Watch for run-on sentences • Run-on sentences are sentences that run together because they are missing punctuation • Here is a run-on sentence you can’t tell where the first sentence ends and the next begins because I didn't put a period after the first sentence.

16. Prepositions • In technical writing (but not necessarily in other forms of writing), we don’t end sentences with a preposition. • Instead of: A preposition is a poor word to end a sentence with. Have : A preposition is a poor word with which to end a sentence. • Example prepositions: for, from with, to

17. Watch for sentence fragments • Usually a sentence fragment is a piece of a sentence that has become disconnected from the main clause; simple fix – change the punctuation • Appalachian State University offers several master’s degrees. Such as Computer Science, Mathematics and Physics.

18. Contractions • Not allowed in technical writing • Instead of: don’t Have: do not

19. Numbers • Small numbers should be spelled out when used as adjectives • The next three sections… • Don’t spell out a number that is not used as a adjective • Section 3 describes …

20. Avoid forms of the verb “be” • Especially avoid starting sentences with “there are” or “there is” • Instead of: There are several techniques… Have : Several techniques exist …

21. Commas • Do not use commas to separate complete sentences • Join closely related sentences with a semi-colon • Instead of: Each speedup is above one, from these results one can see ... Have : Each speedup is above one; from these results one can see …

22. Semi-colons • Only use semi-colons to separate complete and closely related sentences • A comma instead of a semi-colon should be used in the sentence below because the phrase after the semi-colon is not a complete sentence Each speedup is above one; conclusively indicating that the round-robin strategy yields better performance.

23. Quotes • Never quote material unless it is of the same caliber as the Gettysburg address • Don’t quote – restate and cite • Punctuation that follows a quoted section should be enclosed by the quotation mark as in: “I can’t come to class today,” she replied.

24. Say what you mean • Unlike poetry , technical writing has to be precise and clear • Two papers by Norris and Fenwick … • Does this mean one paper by Norris and one by Fenwick? • Or, does this mean two papers authored by both Norris and Fenwick?

25. This and it • Avoid “this” and “it” when they don’t make clear the topic under discussion. • Instead of: This data agrees with the results found by Norris. Have: The data in figure 3.2 agrees with the results found by Norris.

26. The article the • Definite article • The book is on the table. “The” implies a specific book. • Can use or omit with non-count nouns Either of these works: • I love to swim in water. (as opposed to mud)‏ • I love to swim in the water.

27. More on the article the • the used with an abbreviation for a noun • Good: • The ACM is a fine organization. • ACM is a fine organization. • The IBM company makes lots of money. • IBM makes lots of money. • Bad: • The IBM makes lots of money.

28. More on the article the • Certain nouns have their own rules • Usually not used with countries • Germany is .. (correct)‏ • Austria is .. (correct)‏ • But • The Germany is .. (incorrect!)‏ • The United States (correct)‏ • This inconsistency makes the a real challenge for non-native English speakers/writers

29. The articles a and an • Indefinite articles • A book is on the table. “A” does not indicate a specific book. • Using a or an depends upon the beginning sound of the word that follows the article • A University, a dog – consonant sound, use a • An elephant, an idiot – vowel, use an • Only use with a count noun (implies quantity)‏ • A bottle of water; not a water

30. Don’t use a hammer on your reader • In other words, don’t use the same word over and over. For example, Another option is library modification that intercept and redirects all calls to unsafe functions to the modified library with the modified functions.* *Actual excerpt from a CS 3481 paper

31. A note on writing summaries • Don’t use “the article” or “the authors” to indicate the source of your information • For example, • Instead of: The article begins by explaining the technical definition of a buffer overflow. Have : A buffer overflow occurs when the size of the input read by a program is larger than the buffer declared to hold the input. • In general, you would cite the source of a statement like above. For a summary of a single article, I don’t require a cite since the source is obvious.

32. Final notes • Don’t wait until the last minute to do your writing • Write, put the paper aside for a day or so and then re-read • Proof-read! • Read it aloud • Get someone else to read your paper • Proof-read!

33. Sources • Armando’s Paper Writing and Presentation Page. http://swig.stanford.edu/~fox/paper_writing.html • Purdue On-line Writing Lab. http://owl.english.purdue.edu • Michael Alley. The Craft of Scientific Writing. Springer Publishing, 1996. • William Strunk, Jr. and E.B. White. The Elements of Style. Allyn & Bacon, fourth edition, 2000. • Nicholas Higham. Handbook of Writing for the Mathematical Sciences. Siam, 1993. • James D. Lester. Writing Research Papers. Addison-Wesley Publishers, 1999. • Kate L. Turabian. A Manual for Writers of Term Papers, Theses, and Dissertations. The University of Chicago Press, 1996.