Connectives for Well-structured Technical Writing by Gene Cooperman, gene@ccs.neu.edu (with inspiration from Rohan Garg) Copyright (c) 2017 This document may be modified and distributed further as long as the copyright notice remains. The author would appreciate receiving copies of any enhancements. =================================================== [NOTE: This note is still in progress. Check back for later versions.] PREAMBLE: The golden rule in all technical writing is to maintain the proper tension between: being precise and clear (even at the cost of repeating phrases to make clear what you are referring to); and keeping the text short. Precise means having no more than one meaning (being unambiguous). Clear means having at least one obvious meaning (without struggling to parse some complex grammar with, for example, many dependent phrases). Hence, the ideal text is as short as possible, while still maintaining the natural redundancy of precise, clear writing. Next, the key to organizing a paper is paying attention to the topic sentence (first sentence) of each paragraph. If the topic sentences are well-written, then you can read only the topic sentences, and it will tell the "story" of your article. This exercise will uncover things such as a paragraph that it too long, and needs to be split into two halves (with an extra topic sentence for the second paragraph). Finally, the abstract should say what is novel and why it is important. People often write too much in the first version of an abstract. If you do, copy the first version to the introduction, and extract the sentences for novelty and importance to create a short abstract. The title tells the reader if they want to read the abstract. The abstract tells them if they want to read the introduction, and the introduction tells them if they want to read the full paper. =================================================== Part 1: Connective Words Connective words are the key to a logical, technical argument. They change a paragraph from "Fact 1; Fact 2; Fact 3; Fact 4" to "Fact 1; Therefore, Fact 2; However, since Fact 3, Fact 4 must be true". We begin with some basic principles, and then discuss connectives. You can find illustrations of all of these connectives in the following paper: "How Not to Bid the Cloud", by P. Sharma, D. Irwin, and P. Shenoy https://www.usenix.org/node/196313 Please download the pdf and search the text for examples of those connectives. "This, "that" to refer back to a previous sente4nce Re-use same words when referring again to the same concept Guard against using the same word again nearby when it is used in two unrelated contexts Phrase in apposition to a noun: put commas around the phrase Test of correctness: can you remove the phrase in apposition and the sentence still makes sense? parallel structure: same part of speech for each part (e.g., a noun or an -ing word or a verb) Short sentences: if there are too many verbs or too many phrases, then split the sentence, and use "this", "that", "the previous case", etc., to have the second sentence refer back to the first. ", which" versus "that" Test of correctness: If "which", can replace it by start of a new sentence. If "that", cannot trivially split into a separate sentence. The word "so" has two meanings: because: a conjunction between two sentences therefore: an interjection at the beginning of a sentence "i.e.," -- final comma needed, synonymous with "That is," Connectives: However, Hence, Instead, For example, Specifically, Similarly, TEST: can we remove the interjection word at the beginning? Finally, TEST: can we remove the interjection word at the beginning? TEST: there should be a previous list of categories or cases, and this is the last category or case. Further, TEST: can we remove the interjection word at the beginning? TEST: additional information not previously captured Since ..., Test for correctness: can the phrase with "since" be moved (for example, moved from the beginning of the sentence to the end of the sentence, with a comma to separate out the phrase. Thus, Therefore, TEST: can we remove the interjection word at the beginning? TEST: can we reduce this and a previous sentence into "if ..., then ..."? Furthermore, In addition, In particular, TEST: can we remove the interjection word at the beginning? While ..., Even though ...,, TEST: can we replace the pattern "While ....A.., ...B..." by ...A... However, ...B... ..., as ... TEST: Is "as" a synonym for "since"? , such as optional word "then" is sometimes omitted optional phrase "in order to" is sometimes reduced to "to" In both cases, when in doubt, use the full phrase. First, ...A... Second, ..B.... Can be used to create a high-level delimiter in which ...A... and ...B... might even be separated by multiple sentences or even a paragraph. ============================ Part 2: Other Principles of Grammar in Technical English: In technical writing, we are extra strict about the grammar rules in order to avoid ambiguity. In an English essay, writers will sometimes add ambiguity on purpose because a sentence then has a double meaning or an extra connotation that enriches the beauty of the sentence. In technical writing, we want a single, unmistakable meaning, with absolutely no ambiguity. This is done through extra strict grammar rules that makes the language boring from an essay viewpoint, but very precise. 1. We avoid pronouns, unless the pronoun really refers to the last noun phrase. GOOD: We have developed a compact operating system. We are calling it a micro-kernel. BAD: We have developed a compact operating system with a special library of modules. We are calling it a micro-kernel. [ The library of modules is not a micro-kernel. ] BETTER: We have developed a compact operating system with a special library of modules. We are calling this operating system a micro-kernel. BEST: We have developed a compact operating system. This operating system includes a special library of modules. We are calling this operating system a micro-kernel. [ RULE: When the grammar becomes complex, break up the sentence into several shorter sentences.] 2. 'which' versus 'that' (repeated from Part 1, but it's important): 'that' is used to further restrict the meaning of a noun phrase. 'which' is used to add extra information about a noun phrase. ALSO: 'which' always employs a comma. 'that' almost never employs a comma. EXAMPLES: 'which': 'We have developed a compact operating system, which includes a special library of modules.' 'that': 'An operating system that is built on top of a micro-kernel is often more maintainable.' 3. In English, if two adjectives modify a single noun, we use a ',': 'a rich, happy life' In essays, a more verbose form is 'a rich and happy life', but that is rare in technical writing. In English, a noun is sometimes used as an adjective. An example is 'source code'. In this case, the rules change when we try to apply two adjectives, and one adjective was originally a noun. We write: 'the Java source code' (no comma) where 'Java' and 'source' both modify 'code'. But what happens when we have a phrase, 'open source' that modifies 'code'? Then, we might write: 'open-source code', 'open-source Java code', etc. The '-' is used to bind 'open' and 'source' together before attaching them to 'code'. Hence: 'I am working on some open-source Java code.' but: 'The Java code that I am working on is open-source.' 4. Parallel construction using a colon (':') and semi-colon (';'). EXAMPLE: A micro-kernel-based operating system is: a. built upon a small core; b. provides a well-defined interface; and c. allows additional operating system modules to execute with reduced privileges. INLINE VERSION (saves space): A micro-kernel-based operating system is: built upon a small core; provides a well-defined interface; and allows additional operating system modules to execute with reduced privileges. BAD (NON-PARALLEL) VERSION: A micro-kernel-based operating system is: a. compact; b. built upon a small core; c. it provides a well-defined interface; and d. you can add additional operating system modules that execute with reduced privileges. [ The problem here is that a/b/c/d each begin with a different type of phrase. While it uses legal English grammar, the lack of parallel phrasing means that the reader has to stop and separately parse each phrase. ] 5. A style without "I" and "we" is preferred. Compare: a. The SuperWhiz package was developed using sockets. It provides a high-level abstraction, which also improves the reliability for large messages. b. We developed the SuperWhiz package using sockets. Our package uses a high-level abstraction, which also improves the reliability for large messages. Which one sounds like it is describing "objective truth", and which one sounds like it is boasting about how smart the author is? 6. Small numbers are usually written in English. Large numbers are usually written as digits. The principle is that if you are counting the number of things, you use digits: "There were 9 teams present, with each team having two members." 7. In technical writing, a single word should always be used for the same meaning. If a word has two meanings, choose a synonym word for the second meaning. Similarly, if there are two synonym words that refer to the same meaning, then choose just one of the words in your paper, and make sure to avoid the synonyms. 8. If the technical meaning of a word or phrase is not known to some of your audience, then you must define it the first time that you use it. It's usually helpful to place the word or phrase in italics when it is being defined. If the word/phrase has an acronym (abbreviation), then place the acronym in parentheses after the word/phrase. Note that this implies that you must know your audience. Whether to define a word depends on who your audience is. 9. Clarity comes first. You can break any rule (including this rule :-) ) if that will make the text clearer.