Diff for "DrAndersonsRulesForWritingPapers"

Dr. A's Rule for Writing

Taken with permission and modified from "Dr. Choueiry's Golden Rules for writting papers" 12/1/2006.

When writing a report or a thesis, get quickly to the point. Do not lose time making general statements about the state of science, technology, or world politics that are not DIRECTLY relevant to the subject matter. The shorter your document, the better. The reader really does not have the time for tangent discussions.

1. Focus on YOUR contribution.
2. Address related work ONLY as it affects your work DIRECTLY.
3. Keep background information as short as possible: your report is NOT a tutorial

Make sure to check your grammar. If you are not sure about some grammatical rule, take a look at Your Complete Guide to English Grammar: Learn Grammar Rules and Concepts and/or use Grammarly.

GOLDEN RULES for writing and formatting

BEFORE YOU SUBMIT YOUR REPORT/PAPER/THESIS FOR PUBLICATION OR TO ME, PLEASE RUN CAREFULLY THROUGH THE CHECK LIST BELOW:

1. Refer to the 'components' of your document always in capital letters, as follows:

     Chapter~\ref{chap:x},
     Section~\ref{sec:x},
     Figure~\ref{fig:x},
     Equation~(\ref{eq:x}) (notice the parentheses!),
     Table~\ref{tab:x}, etc.

     Notice the use of the ~ sign between the keyword and the reference.
     It prevents the two from being split between two lines.

2. NEVER have the titles of a section and subsection without texts between them.
3. NEVER have a section with a unique subsection: rethink and restructure your text.
4. Use active and not passive form (e.g., "we have shown" and not "it is shown", see expanded discussion below).
5. Each sentence has a subject, verb and object (no place for poetry).

6. Do not confuse the use of "that" and "which" (in American English). If you don't know the rule, please learn it from which versus that

7. The words "e.g." and "i.e." are Latin words and stand for "exempli gratia" (meaning for example) and "id est" (meaning that is). When used within parentheses (i.e., as I am using then in this statement), they must be followed with a comma. When used inside the sentence, e.g. as used in this statement, they should NOT be following by a comma.
8. When using "e.g." and giving several examples, make sure you include a comma between examples and an "and" before the last alternative (e.g., an apple, an orange, and a prune). Also, make sure that you do NOT include an "etc." because you are simply giving examples. Do not use: "e.g. an apple, an orange, and a prune, etc. This is wrong.
9. Run a spell checker (M-x ispell-buffer for emacs)

10. All captions are in \small and end with a full-stop (that's a period). Your LaTeX class should do this for you.

11. All figures/tables are referenced in the text, *before* they appear. Figure/table citation and the figure/table itself should be as close to each other as possible. You may need to move a figure around to get LaTeX to place it on the page you prefer, so there are exceptions to this rule.

12. All sentences end with a full-stop (That's a period please!).
13. NEVER separate a subject (no matter how long) and its verb by a comma.
14. There is NEVER a space between a word and the following punctuation mark.
15. There is ALWAYS a space between a word and the preceding punctuation mark. (A space must appear AFTER a punctuation mark and not BEFORE it).
16. All words are correctly capitalized.

17. All citations are correct and complete. Never put a breaking space between the word preceding the citation and the citation. Instead always put a non-breaking space = ~. E.g. "Anderson~\cite{anderson2023} shows the increase in popularity of Canvas rising to 58%." Here the tilde is key!

18. Citations should always reveal information about the topic at hand. Please do not write a meta-data sentence and then add a citation. E.g. "The choice of the sorting algorithm impacts efficiency across various scenarios, and different algorithms have varying speeds. [10]" There are several problems with this sentence:
    • Any 2nd year programmer should know this to be true, there is nothing worth citing here.
    • The second half of this sentence adds nothing. Change to "...impacts time and space efficiency."
    • I know - you wanted to cite this paper. Great, but cite the results, not the obvious platitude. "Table 1 shows the relative speeds and space efficiencies of the most common sorting algorithms." Now you cite it in the caption of the table, and you have imparted some real knowledge to the reader.

19. All acronyms are properly defined on first use. Give the description and add the acronym in paranthesis e.g., backtrack (BT) and forward checking (FC)

20. The first time a new term is used, it can be italicized for emphasis. In LaTex use {\em term\/}.

21. NEVER use bold face {\bf xxx} or underline \underline{} in the text. It is used in titles of sections, figures, and tables.
22. All definitions are formally introduced.
23. All Equations are numbered and centered.
24. In your pseudo-code.
    • All `commands' (while, if, repeat) are in bold (\bf).
    • All functions are in small caps (\sc)
    • All constants are in courier (\tt)
    • All your variables are properly initialized/introduced
    • Input/output properly defined.
25. The 3-noun rule: Engineers have a bad tendency for using 4 or 5 nouns, which is totally confusing. For instance, they can write: "The third world hunger ending campaign division"
    • First, NEVER use more than 3 nouns in a sequence:
      • "Division of ending-hunger campaign in the third world" (I know the latter is not particularly nice, but it is far better than the former.)
    • Second, you need to add a hyphen between the two nouns whose meanings are the closest. For example, write: third-world hunger, problem-solving skills, interactive problem-solvers, etc. Check the Chicago Manual of Style for more details about the rule.
26. Never use informal English. Never use the form: "So, we decided, etc." Instead, you may use the form "Consequently," "As a result," "Thus," "Hence," etc.

27. Do not use the phrase, "it seems like." Words such as: should, seems, think and appears should be avoided. Search and replace them with more direct statements. (note: This includes any variation that you might like to use, including gives the impression etc.)

28. Never use the word "I"
29. Never use "it's" in technical writing. Use either "it is" or "its," whichever applies. If you stick to this rule, it will be harder to make the mistake.
30. Replace all
    • "can't" with "cannot"
    • "don't" with "do not"
    • "didn't" with "did not"
31. Never use the pattern "This shows..." Be specific what "this" means. Write "This fact/experiment/behavior/ shows...." To detect the occurrence of the pattern "This shows..." I find that it is helpful to search for every occurrence of the word "this" and see if it is followed by a noun (e.g., "this graph", "this algorithm", and "this worst case"). Otherwise, a noun probably needs to be added or the sentence reworked. Note that a similar rule may be created about the word "that" (keeping in mind that "that" has more meanings than "this").
32. When reading what you wrote, systematically strike every occurrence of the word "very."
33. Some words in English derive from Latin and their plural forms can be challenging. Here are some examples (singular/plural): criterion/criteria, datum/data (datum is seldom used and data is a word in plural), focus/foci (altough focuses is accepted today), formula/formulae (although formulas is sometimes used today), phenomenon/phenomena, optimum/optima, maximum/maxima, medium/media, minimum/minima, scenario/scenarii (although scenarios is pretty well accepted today), etc.
34. Do not include bibliographic references in the title of a chapter, section, sub-section, or sub-sub-section.
35. Correct use of the expression "we denote":
    • We denote the set of elements by X
    • We denote the set of elements as X
36. Some reviewers require that references be listed in a uniform way: either you include the first names of all authors, or you put only the initials. Choose one option or the other and stick to it. When using the initials do not leave a space between the initials of the first and middle names: Joel M. Gompert is abbreviated J.M. Gompert.
37. Thou shalt not cite Wikipedia or other onlines sources that are not authoritative (see Bibliography Guidelines expanded below).
38. Do not give a long list of authors. If there are more than two, give the primary author and append et al. e.g. Scot Anderson et. al. (For additional guidelines on the Bibliography see below)

Passive Voice

Identify where you used a passive form and replace is with an equivalent active form by doing a search for the following words:

• "is" "are" "was" "were" "be" "been"

Unless I'm forgetting something, searching for these words will locate all uses of the passive form. If the word is followed by a predicate (i.e., a noun or adjective) then the form used is active. If the word is used in the continuous sense (i.e., it is followed by a verb with -ing, e.g. "is running"), then it is active. Otherwise, it is probably a passive form.

When in doubt, look at the definition: A verb is in the passive voice when the subject of the sentence is acted on by the verb. For example, in “The ball was thrown by the pitcher,” the ball (the subject) receives the action of the verb, and "was thrown" is in the passive voice. (From Dictionary.Com)

Using is, was etc. is not always passive, but it can create wordy and confusing sentences.

Example: The reason that we created our own CSS for our webpage was that we always added custom styles to change the way Bootstrap formatted HTML elements.

Fix 1: We created our own CSS for our webpage because we always added custom styles to change the way Bootstrap formatted HTML elements.

Fix 2: Bootstrap did not format HTML elements to suit our needs; therefore, we created our own CSS framework.

For some non-computing examples see: https://www.hamilton.edu/academics/centers/writing/seven-sins-of-writing/1

BIBLIOGRAPHY GUIDELINES: FORMATTING, STYLE AND CONTENT

1. In a report or in a thesis, use the named style for the bibliography unless otherwise required.

2. In a paper, follow the publisher's requirements. Note: in our department we usually use IEEE (see p. 7) style.

3. In the named style, use \shortcite{} and \cite{} as follows:

         Bush~\shortcite{Bush:2002} set the standard for
         responding to terrorist activities....

         The rules for democratic elections for ..... are set
         in~\cite{Ford:1979}.

1. Always reference citations in the paper, NEVER use a \nocite!

Additional Tips that may make it into the rules group some day

1. Never say, "It is important to note...." If it is important, note it. If it was not important you would not have included it (hopefully).
2. BE CONCISE! Avoid wordy phrases and sentences.