Survey paper (Part 4) Deadline: end of Friday, April 21 [ For Part 1, it is "very late" at the end of April 7. ] [ For Part 2, it is "very late" at the end of Thurs., April 13. ] [ For Part 3, it is "very late" at the end of Tues., April 18. ] ### Copyright (c) 2023 by Gene Cooperman (gene@ccs.neu.edu) ### This file may be freely copied and modified as long as ### this copyright notice remains. ### (While it is not required, it is hoped that some people will contribute ### back text or suggestions on how to improve this series, in order ### to help students and others improve their technical writing.) For Part 4, you should correct any comments or feedback from Part 3. The rest of Part 4 is learning the tricks that a good human editor will use to improve your writing. Learn the rules below, and apply them. If you decide that you were already following the rules below, then that's great. You can re-submit your previous Part 3 as your new Part 4. But as before, the grade is cumulative. Even if you had a perfect score on Part 3, your score could go down if your text is hard to understand because you are not following the suggested rules below. Also, I have created: https://course.ccs.neu.edu/cs7600/WRITING/paragraphs.py Try downloading it, and doing: ./paragraphs.py MYFILE.md It will try to find overly long sentences, paragraphs, and too many paragraphs in a single section. It is provided as advice, but ultimately, you will still be the one to decide what is too long to easily read. First, as in Part 3: 1. You should now have approximately 5,000 words. 2. The topic sentences of the paragraphs should tell a story. 3. The sentences within each paragraph should flow. * Concerning the flow within an individual paragraph, recall that there are two common models for making the sentences flow: a. The stress of the last sentence should match the topic of the next sentence. b. In a parallel structure, the previous stress states a category, and the topics of the next few sentences each match the original stress. --- Next, for Part 4, you must polish your text in several specific ways: 1. Any overly long paragraphs should be split up (while still ensuring that your topic sentences tell a story). 2. Any overly long sentences should be split up (while still making the paragraph flow). 3. Any overly long sections (for example, 8 or more paragraphs) should be broken up by using subsections ('##'). If you have many subsections, then your original section should start with a paragraph reviewing the organization of the subsections. 4. Consider adding connecting phrases where appropriate. It is the connecting words that explain to the reader what is the connection between the previous stress and the next topic. * Don't make the reader work hard to figure out the connection. You're the one who is supposed to be writing this -- not the reader. :-) To apply connecting phrases: Look at the match between the previous stress and the next topic (either withing the story or within a paragraph). If the topic is an example, say "For example". If it's a special case, consider "However". If it's a consequence of the previous stress, consider "Therefore" or "So". Sometimes, you may need a longer connecting phrase like "While there do exist some counter-examples, most instances are ...." In case you have trouble coming up with your own connecting words, here is a rich selection often found in technical articles: * therefore, so long as, because of, yet, due to, more generally, specifically, especially, in the case of, next, then, while, in order to, 'below' or 'above' (citing earlier or later text), because, since, for details ... see ..., as shown in, as seen in 5. Pronouns should almost always refer to the nearest noun phrase. If not, expand the pronoun into a copy of the noun phrase that you're referring to. This may seem redundant because you already know what the pronoun refers to. But the reader has to stop and search. * Don't make the reader work hard to figure out what the pronoun refers to. You're the one who is supposed to be writing this -- not the reader. :-) 6. Avoid synonyms where possible. It may seem redundant to constantly use the same phrase for the same concept, but it makes the reader work harder when you switch to a new phrase for exactly the same concept. * THIS IS WRONG: A call to a function will pass arguments to the parameters in the definition of the subroutine. * Don't make the reader work hard to figure out if this is a new or old concept. You're the one who is supposed to be writing this -- not the reader. :-) 7. Parallel structure: Use the same part of speech in a list. Do _not_ write: * There are three kinds of actions: reviewing code; summarizing code; and an overview of the code. If you wish, you can emphasize items within a list. EXAMPLE (with optional use of number: i, ii, iii): * There are three kinds of actions: (i) reviewing code; (ii) summarizing code; and (iii) presenting an overview of the code. 8. SYNTAX: If you use a colon (':'), then you should usually use a semicolon (';') to separate items. This helps with longer items, and with items which need a comma in the middle. (EXCEPTION: A list of single words or two-word phrases can use a comma to separate the items.) 9. FORMATTING: Consider highlighting important lists that the reader needs to refer back to. Markdown uses '*' or '1.', '2.', .... Latex uses \begin{enumerate}/\begin{itemize} ; \item ; \end{enumerate}/\end{itemize} Latex offers '\item[(i)] ...' and so on, if you want to choose your own numbering. IMPORTANT: Just because you've chosen to highlight a list doesn't mean that you can now forget the rule of colon (':') and semicolon (';'). EXAMPLE: There are three kinds of actions: \begin{enumerate} \item reviewing code; \item summarizing code; and \item presenting an overview of the code. \end{enumerate} 10. SYNTAX: The word 'so' has two meanings, with two different syntaxes. Don't confuse the two. EXAMPLE: I'm going to the store, so I can buy some food. [ 'so' means 'in order to'. Here, 'so' could be replaced by the longer phrase 'so that'. ] EXAMPLE: I'm going to the store, so as to buy some food. [ 'so' means 'in order to'. Here, 'so' has been replaced by the longer phrase 'so as to'. ] EXAMPLE: I was hungry. So I went to the store. [ 'So' means 'Therefore'. In this meaning, it usually begins a new sentence, and is capitalized. ] (THIS IS WRONG: "I was hungry, so I went to the store.") 11. SYNTAX: Know the difference between the connecting words "that" and "which". EXAMPLE: "I chose the first book that I saw." [ "that" is used to specify which one or to disambiguate. There were many books. I chose a particular book: "the first book that I saw". Usually, we do not add a comma (',') before "that", since it is tightly bound to the phrase that it modifies. ] "I chose the book 'Tom Sawyer', which happened to be the first book that I saw." [ "which" is used to specify additional information. It is not required for the core meaning of the sentence. "I chose the book 'Tom Sawyer'." is the essential meaning, and everything else is additional information. Usually, we add a comma (',') before "which", since it is _not_ tightly bound to the phrase that it modifies. ] And here is a useful tool for those who are not native English speakers. 1. Write your text in English, as usual. 2. Copy each paragraph into translate.google.com or deepl.com, and translate it to your native language. (You will have to remove newlines when copying your text to the web site.) 3. Click on the double-arrow icon to reverse the translation. You now have a translation from your native language to English. 4. Compare this English version to your original English version. Google and Deepl are not always right, but they can often suggest patterns of translation into native-sounding English, since they were trained on examples emphasizing native English patterns. You all can look at two phrases (e.g., yours and Google's) and immediately decide which phrase sounds more like the phrase of a native English speaker. Let Google/Deepl suggest alternatives, and then use your own ability to chose the phrase that "sounds better". An alternative is ChatGPT, using the commands "Proofread [or Paraphrase] the following paragraph." And finally, a word about tenses: 1. Try to use the same tense within a single paragraph. ("The work is successful." and "The work has been successful." are both present tense, in case you need to indicate what happened first and what happened second.) (Similarly, "The work was successful." and "The work had been successful." are both past tense, in case you need to indicate what happened first and what happened second.) 2. Try to avoid the future tense. 3. Try to avoid saying "we" too much. ("The experiments show that ...." is better than "We show that ....". This formal style comes from the original idea that scientists _discover_ existing laws of nature. They don't personally invent new laws of nature.) 4. And as always, if the rule makes the language sound artificial, then go ahead and break the rule. But know the rule first, and then you can make an intelligent decision on when to break the rule. === Submitting: We will continue to use markdown syntax. In hw6-surv-part1.txt, I provided standard pandoc commands to help you display your markdown in your favorite format. You will submit _only_ your Markdown (.md) file (without using 'tar'). As usual, you will submit with a submit script: /course/cs7600/homework/submit-cs7600-hw6-surv-part4 mysurvey.md