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

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).

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.

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.

18. All acronyms are properly defined. Example: backtrack (BT) search. forward checking (FC)....

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

20. NEVER use bold face {\bf xxx} or underline \underline{} in the text. It is used in titles of sections, figures, and tables.
21. All definitions are formally introduced.
22. All Equations are numbered and centered.
23. 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.
24. 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.
25. 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.

26. 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. Included gives the impression etc.)

27. Never use the word "I"
28. 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.
29. Replace all
    • "can't" with "cannot"
    • "don't" with "do not"
    • "didn't" with "did not"
30. Never use the pattern "This shows..." Be specific what "this" means. Write "This fact/experiment/behavior/ shows..."
31. When reading what you wrote, systematically strike every occurrence of the word "very."
32. 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.
33. Do not include bibliographic references in the title of a chapter, section, sub-section, or sub-sub-section.
34. Correct use of the expression "we denote":
    • We denote the set of elements by X
    • We denote the set of elements as X
35. 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.
36. Thou shalt not cite Wikipedia or other onlines sources that are not authoritative (see Bibliography Guidelines expanded below).
37. 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.

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").

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)

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.