Recipe for Technical Writing (c) Gene Cooperman, 2020 (This note may be freely copied and modified as long as this copyright notice remains. I would appreciate any enhancements being sent back for possible inclusion here.) The goal of this technical writing exercise is to separate out the creative portion of technical writing from the more mechanical style issues. One can draw an analogy with writing a computer program, in which the program design and algorithm used form the creative portion, and the function implementation, syntax, and coding style form the more mechanical part. The rest of this note is divided into PART I (mechanical) and PART II (creative) for technical writing. ==== PART I: MECHANICAL (STYLISTIC) PORTION OF TECHNICAL WRITING First, let's discuss the more mechanical side. In the body of the paper, let's analyze it from higher-level to lower-level: A. Read the topic sentences from each paragraph (Does it tell a story?) B. Use connecting words between sentences of a paragraph (or to connect to a previous paragraph). The file 'writing-technical-papers.txt' has some examples of connectives commonly used in technical writing. C. [Gopin and Swan]: Each sentence has a topic and a focus (stress). (As a test, try reading just the early topic portion of each sentence in a single paragraph. Does it hold together or does it sound confused?) Gopin and Swan RECOMMENDATIONS: Make sure that the topic appears first, the focus is last (in stress position), and that they are connected by a verb. * For further details on topic and focus, see: https://cseweb.ucsd.edu/~swanson/papers/science-of-writing.pdf * On a first reading of that paper, concentrate especially on just two sections: "The Stress Position" (three pages) "The Topic Position" (four pages) * Even if you don't have time to read those two sections in detail, please note the authors' summary principle: "Put in the topic position the old information that links backward; put in the stress position the new information you want the reader to emphasize." If you correctly apply the rules of topic and stress position within a paragraph, then you should see a better flow from stress to topic of the next sentence inside a paragraph to test if it tells a connected story. Note that we applied the above principles (topic sentence, connectives, and topic/stress for each sentence) in reading the classic paper: UNIX Time-Sharing System https://people.eecs.berkeley.edu/~brewer/cs262/unix.pdf REMARK: The recipe above is intended to help you see your own writing in the same light that a third person would see it. The problem of good writing is that you already understand everything and it is hard to see your writing from the point of view of others. REMARK: As you absorb this recipe, consider adding some smaller rules that may help you: (i) Sometimes you have a list. A sentence might have three stresses: "The most common approaches are syntactic, semantic, and hybrid." Your next three sentences should then follow a strictly parallel construction (i.e., a single grammatical template): "The syntactic approach is used .... The semantic approach is used .... The hybrid approach is used ...." (ii) Avoid synonyms. For one concept, always use the same phrase. (Exception: If there are some synonyms for this concept in the literature, then introduce the synonyms at the first occurrence of the concept. But after that, choose just one phrase for the concept.) (iii) Avoid pronouns. If the pronoun refers to the most recent noun phrase, then that is acceptable. If the pronoun refers to an earlier noun phrase, then replace the pronoun by the earlier noun phrase. (iv) Shorter sentences are better longer sentences. Consider breaking up long sentences into two or more short setnences, with appropriate connective phrases. --- For non-native English speakers, there is sometimes a question on when to use articles before a noun. The following article should be helpful: https://www.quickanddirtytips.com/education/grammar/when-to-use-articles-before-nouns ==== PART II: CREATIVE PORTION OF TECHNICAL WRITING We are now ready for the creative portion of technical writing. We will practice this first in giving a five-minute oral presentation in class, and in then writing an abstract as part of your first draft. ELEMENTS OF THE CREATIVE PORTION (for a lightning talk or an abstract): 5-minute talk or abstract * Novelty: What is new? * Importance: Why should anyone care about this? * How does this relate to the literature? [ Often the answer to this is already contained under "Importance". ] Since we are writing a survey paper, novelty and importance must be re-interpreted as * Novelty of the papers that are surveyed * Importance of the papers that are surveyed How should the novelty be described? -- Please present the novelty for the entire domain or topic area, not just the novelty of your surveyed papers. Think about a taxonomy of novel approaches in this domain. Then say how your surveys fit into this general taxonomy of novelty. This is the fun, creative part! In my grading, there will be no _wrong_ taxonomy of novelty. It's a matter of individual taste how you wish to categorize it. But show the novelty of the individual target papers within this larger context. *** IMPORTANT NOTE 1: Be critical! The authors say that the work is really novel, and that it is really important. What's your opinion? (If you simply repeat the author's opinion, then the reader doesn't need you. They should just read the original papers.) *** IMPORTANT NOTE 2: You must create a general description of the combined technical area represented by the three papers. * What is the novelty of this line of research? * What is the importance of this line of research? * (How does this line of research benefit computer science as a whole?)