How to Write

(How to Prepare Technical Reports)

William J. Rapaport

Department of Computer Science and Engineering,
Department of Philosophy,
and Center for Cognitive Science
State University of New York at Buffalo,
Buffalo, NY 14260-2000

• For general information on how to study, including information on how to decide what to write and how to do the actual writing, see my Web page, "How to Study".

• For general information on how to decide what to write and how to do the actual writing, also see:
  • Andrews, Mark, "Some Elements of an Essay"

  • Harvey, Gordon (2008), Writing with Sources: A Guide for Students (Indianapolis: Hackett).

  • Harvard College Writing Program: Resources for Students
    • Contains several PDF guides to writing in specific disciplines (such as Philosophy and Psychology).

1.2. All papers MUST be word-processed (or typed)

• Use a standard 10-, 11-, or 12-point roman font if possible.
• If you have a choice, the best font to use is "Times Roman".

• "Typos are very important to all written form. It gives the reader something to look for so they aren't distracted by the total lack of content in your writing." (Randy K. Milholland, Something Positive Comic, 07-03-05)

• Re-read your paper carefully, to catch garbled sentences, misspellings, etc.

• Don't rely on a spelling checker: It can't tell you whether to use "their", "there", or "they're".
  • But I can. :-) See below.

• On Unix, I strongly suggest that you learn to use the vi or emacs text-editors, the LaTeX-2e word-processor, and the ispell spelling checker.

• Errors that you discover when proofreading can best be corrected electronically (for word-processed papers) or by using correction tape or correction fluid.

• Remaining errors might be liable to legal fines! See Liptak, Adam (2004), "Judge Finds a Typo-Prone Lawyer Guilty of Bad Writing", The New York Times (4 March): A16.

1.4. What kind of paper?

• Use 8½" x 11" laser or inkjet print-out (or type on bond paper; if typing, do not use onionskin or corrasable paper). The paper does not have to be laser- or inkjet-printed; dot-matrix printing, however, should be dark enough to be legible. Oversized computer printouts (the kind with guide-holes) should be trimmed, if necessary, to 8½" x 11".

1.5. Do not use double-sided printing.

• I.e., your paper should be on one side of the page only.

• And please do not try to conserve paper by using the blank side of previously-used paper. That's fine for drafts, but not for the final product to be handed in.

1.6. Number all pages.

• If necessary, do this by hand.

1.7. Do not use running heads or foots (feet?).

1.8. Double space everything you type.

• In LaTeX 2e, this can be done by putting the following in the preamble: \renewcommand{\baselinestretch}{2}

1.9. Margins.

• Use a 1" (no more, no less) margin on all 4 sides of the page.
• In LaTeX 2e, this can be done by using the fullpage package.

1.10. Paragraphs.

• Skip a line between paragraphs, and ...
• ... indent new paragraphs 5 spaces (approximately ½") from the left margin (or use \parindent 0.5in in LaTeX 2e).

• Begin the first page of your paper using the following format:
  TITLE OF PAPER
  Your Name
  Date
  Number and title of course

• Then skip 3 lines and start your paper on the same page.

• The title of your paper should be descriptive (not: "Term Paper").
  • If you want to use a "cute" title (e.g., "Trials and Tribulations"), be sure to have a subtitle that is descriptive, separated from the cute title by a colon (e.g., "Trials and Tribulations: A Complexity Analysis of Three Sorting Algorithms").
    • For a recent news article on the use of colons in titles, see Jacobson, Jennifer (2004), "No Mark of Distinction", Chronicle of Higher Education (9 January): A14-A15.

1.13. Don't do any of the following!

• Use a cover page (including printout cover pages)
• Use blank pages in the beginning, middle, or at the end
• Use expensive folders or binders.

1.14. Include an Abstract.

• Every paper should have a 1-paragraph ABSTRACT that very briefly and telegraphically outlines the paper.

• It is also very helpful to have an introductory paragraph that does the same thing, but less telegraphically.

• The abstract should appear immediately after the title information (i.e., after the 3 spaces; see above) and before the paper itself begins.

• For useful information on how to write an abstract, check out some of the websites on this topic; for the latest list, do a google.com search on "how to write an abstract".

• For a humorous template for an abstract, see this PHD cartoon :-)

1.15. Do not use a table of contents.

1.16. Use a staple.

• If your paper is more than 1 page long, put one staple in the upper left corner.

• If you don't have staples or friends with staplers, or if your paper is too large to staple, then use a paper clip or binder clip.

• Do not fold down the corner or use tape.

• Oversized computer printouts should be trimmed, burst, and stapled.

1.17. Separate sentences with precisely 2 blank spaces.

• LaTeX 2e will do it automatically, but will also add those extra spaces after any period (or question mark, or exclamation mark), whether you want it to or not, unless you tell it not to; see the LaTeX 2e manual for details.

• Footnote (or endnote) numbers should always follow punctuation.[1]

• Footnotes (which appear at the bottom of a page) are easier for readers than endnotes (which appear at the end of a paper). (But on Webpages, endnotes are just about the only possibility.)

"One picture is worth a thousand words, provided one uses another thousand words to justify the picture." — H.M. Stark, cited in American Mathematical Monthly 102 (1995) 751.

• In reading many term papers, research reports, dissertations, and dissertation proposals, I have noticed that many people have diagrams with lots of lines of various kinds: solid, dashed, dotted, with and without arrows, etc., and lots of closed curves of various kinds: circles, ovals, squares, rectangles, etc. All too often, the diagram lacks a useful caption or legend.

• Be very careful when including such "box-and-arrow" diagrams ("boxology", flow-charts, etc.) in your papers.

• They are never self-explanatory. Therefore, you must include, either in the caption or in the text, a description of its "syntax and semantics". That is, you must describe what every box represents and what every arrow represents.

• If you find this hard to do, then there's probably something wrong with your diagram. (And if you find it hard to figure out, imagine your poor reader!)

• The formal term for this is "failing to provide a semantics for your syntax". Recommended reading:
  McDermott, Drew (1981), "Artificial Intelligence Meets Natural Stupidity", in John Haugeland (ed.), Mind Design: Philosophy, Psychology, Artificial Intelligence (Cambridge, MA: MIT Press, 1981): 143-160.

  
  

1.20. Keep Your Audience in Mind:

• One thing that can help you decide what to write or how to say it is to think of the intended audience. Who is going to read your paper? (Your instructor, probably, but he or she already knows why you're writing the paper, so you want to consider your "imaginary" audience in that case.) What do they already know, and what will they need explained to them?

• Keeping the answers to such questions in mind can help you decide what to include or exclude, how much explanation to give, what references to cite, etc.

1.21. Edit Your Paper:

• Besides proofreading your paper, you should also edit it for:
  • readability and clarity (is it clear and easy to understand?),

  • consistency (do you say contradictory things?),

  • completeness (did you leave anything out?), and

  • redundancy (did you say too much about something?).

• Use the technique of "slow reading" to make sure that everything you say is readable, clear, consistent, and non-redundant, and that you haven't left anything important out.

• Give your paper to a friend to read, to get critical advice from someone else.

• Or use Peter Elbow's "Steps for Quick Revising".

1. The single best book on writing is:

   Strunk, William, Jr.; & White, E.B. (1918/1935/1959/2000), The Elements of Style, 4th Edition (New York: Allyn & Bacon/Longman/Pearson).

   • Publisher's website
   • Amazon.com Online Reader
   • Google Books website
   • 1918 edition online
   • 
     However, for a contrasting viewpoint, see:
     Pullum, Geoffrey K. (2009), "50 Years of Stupid Grammar Advice", The Chronicle [of Higher Education] Review 55(32) (April 17): B15–B16.

2. Gillman, Leonard (1987), Writing Mathematics Well: A Manual for Authors (Washington, DC: Mathematical Association of America).

3. Knuth, Donald E.; Larrabee, Tracy; & Roberts, Paul M. (1989), Mathematical Writing (Washington, DC: Mathematical Association of America).

4. Also see below.

• Preferably as if they were papers at a professional conference.

• Some advice from Stuart C. Shapiro:
  In the real world, you will be expected to write papers, either for presentation at conferences, publication in journals, or presentation to your boss or co-workers. No one reads computer programs except the programmer him- or herself, or someone else who has to modify the program. Users and other people want to read about the program, what it does, how it works, etc., and to see it in action. Consequently, the main product of your work is the paper, not the program! In the paper, you should say what you have done, and say (in English summary, not in programming detail) how you have done it. It should also include annotated examples of your program in action. These should be well chosen to illustrate the range of performance of your program. The examples should not be redundant, nor included merely because they look complicated. Each example should illustrate a particular ability of your program. Nevertheless, the reader will assume that your program does nothing interesting that isn't illustrated! You should read Shapiro, Stuart C. (1999), "NimLearn: A Learning Nim Player", to see an example of a such a paper. By reading that paper, you might also learn some good Common Lisp programming techniques. (You can run the nimlearn program by running ACL, and loading /projects/shapiro/AIclass/nimlearn.)

  The program listing should either be presented as figures throughout the paper, or as an appendix. In either case, the listing is included as documentation for what you say in the paper.

• Each project report must be:
  • typed or printed from a computer file
  • double-spaced
  • on 8½" x 11" paper, with any oversized computer printouts burst and trimmed to that size
  • with your own title page (not the one generated by the printer)
  • stapled in the upper left corner.
  • Please do not use folders or covers, unless your report is too thick to be stapled.

• Each report must consist of the following components:
  1. descriptive title (not: "Project 1")
  2. your name, the course number, and date completed
  3. abstract of project (a 1-paragraph summary)
  4. description of the project, in the form of a term paper
  5. list of references (if appropriate) (see below)
  6. an appendix, consisting of:
     • annotated sample runs,
       • The reader should be able to read and understand the sample run (or "demo") without having to refer to the paper.

       • But the paper can and should clarify important parts of the demo.

     • followed by well-documented and commented code (e.g., self-documenting code)
       • There should be enough coments so that someone else a year from now (or a future version of yourself!) could read and understand the program enough to be able to revise it.

       • For general guidelines on how to comment code, see "General Style and Coding Standards for Software Projects".

3.1. DON'T PLAGIARIZE! NOT EVEN ACCIDENTALLY!!

• If you use someone else's words, enclose them in quotation marks ("/").

• And give a full citation.

• In the body of the paper, please refer to bibliographic items using the format:
  Last_name year

• For example: Rapaport 1986.

• Parentheses in various places are optional; see above for examples

• Do not use numerical or letter+numeral abbreviations, such as: [3] or [RAP86], which are cryptic at best.

3.4. References.

• There should be a REFERENCES section at the end of the paper.

• It should list all and only those works explicitly cited in the paper.

• The list should be in alphabetical order by first author's last name.

• Although I prefer the following formats, the exact format is not as important as having all the following information:

  For an article:

  Last_name, First_name (year), "Title", Journal vol: pages.
  • For example:

    Rapaport, William J. (1986), "Logical Foundations for Belief Representation", Cognitive Science 10: 371-422.

  For a book:

  Last_name, First_name (year), Title (city: publisher).
  • For example:

    Schagrin, Morton L.; Rapaport, William J.; & Dipert, Randall D. (1985), Logic: A Computer Approach (New York: McGraw-Hill).

  For an article in a book:

  Last_name, First_name (year), "Title of Article", in Editor_name (ed.), Title of Book (city: publisher): pages.
  • For example:

    Shapiro, Stuart C., & Rapaport, William J. (1987), "SNePS Considered as a Fully Intensional Propositional Semantic Network", in Nick Cercone & Gordon McCalla (eds.), The Knowledge Frontier: Essays in the Representation of Knowledge (New York: Springer-Verlag): 262-315.

  For a Web page:

  Web_Page_Author's_Last_Name, First_name (date of webpage if given, else date retrieved), "Title" [URL_in_brackets]
  • For example:

    Rapaport, William J. (2002), "How to Study", [http://www.cse.buffalo.edu/~rapaport/howtostudy.html].

    • However, you should only use Websites sparingly, preferably only when there is no better published source.

  For further information, see a good style manual, such as:

  1. Harvey, Gordon (2008), Writing with Sources: A Guide for Students (Indianapolis: Hackett).

  2. Turabian, Kate L. (1987), A Manual for Writers of Term Papers, Theses, and Dissertations, 6th edition (Chicago: University of Chicago Press).
     • Also see this shorter, online [PDF] version

  3. The Chicago Manual of Style, 14th edition (Chicago: University of Chicago Press).
     • Also see the online version!

  4. Also see above

Aune, Bruce (2001), "Punctuation and Syntax" [PDF].

4.1.1. Commas (,)

• Use commas to separate clauses linked by "and", "or", "but", etc.
  • For example, "This is the first clause, and this is the second clause."

• Almost never use a comma after "and".

• In general (despite the fact that the very next comma you will see here is an exception!), commas come in pairs (like parentheses).
  • For example, "Commas, which sometimes are used like parentheses, usually come in pairs."

• Use a single comma after an introductory phrase (such as "however", "therefore", "in general", "in this case", etc.). See the previous rule for an example.

• Never use a comma before the main verb of a sentence.
  • For example, "This sentence, should not have a comma where it does."

• Always use a comma before the final element of a series.
  • For example, "one, two, three, four, and five".

• General rule for commas:
  When in doubt, leave them out!

4.1.2. Semi-colons (;)

• Use semi-colons to separate clauses that are not linked by "and".
  • For example, "This is the first clause; this is the second clause."

• Semi-colons and commas should be used together when two clauses are conjoined, and the second one begins with an introductory phrase such as "therefore", "because", etc.:
  • For example: "Clark Kent is Superman; therefore, Kryptonite can hurt him."

• Use semicolons to separate items in a list if one of the items contains a comma (or is itself a comma-separated list).
  • For example: one; two, three, or four; five; and six.

  • For example: Smith 1981; Jones 1989, 1990; and McGillicuddy 1991.

4.1.3. Colons (:)

• Use a colon to signal a comment on the preceding sentence, or to introduce an idea.

• If what follows the colon is a full sentence, capitalize its initial letter.

• But if what follows the colon is not a full sentence, then don't capitalize the initial letter.
  • For example, "This sentence uses a colon: It introduces this new idea."

  • For example, "This sentence also uses a colon: a silly example."

4.1.4. Double quote marks ("/" or ``/'')

• Use them to directly quote what someone else has said.
  • If you use them this way, be sure you quote the author exactly correctly, because any such use of double quotes should be an exact quotation.

• Also use them as "scare quotes", as I just did in this sentence.
  • In general, scare quotes are used to indicate that the phrase enclosed in them is being used in a special way, e.g., being singled out for some reason (as in the above example) or being used in a different way from its normal use (as in the following example):
    • I just "love" it when students turn papers in late.

• Don't use double quotes to emphasize a word or phrase.
  • For example, I just emphasized "Don't" correctly by italicizing it. It would have been incorrect to have written:
    "Don't" use them to emphasize a word or phrase.

    because that would really have been a use of "scare quotes" and would have meant almost exactly the opposite of what I meant.

4.1.5. Single quote marks (`/')

• These are hard to write about on a Web page, since single quotes sometimes don't look good on Web pages.

• Use them to form the name of a word or phrase.
  • For example: `Paris' has 5 letters, but Paris is the capital of France.
    • The above, by the way, is an example of what philosophers and linguists call the difference between "use" and "mention"; the first occurrence of P-a-r-i-s was a mention of the word (I was naming it); the second occurrence was a use of the word. See Swartz, Norman (1997), "Use and Mention", for more information.

  • In this document, I've used double quotes for this purpose (as many non-philosophers do), since they look better in most Web browsers. Linguists often italicize words instead of quoting them; but then they have to use SMALL CAPS for emphasis, instead of italics.

4.1.6. Capital letters

• Use them for:
  • the first letter of a sentence
  • proper names (of people, places, corporations, etc.)

• Don't use them for:
  • the phrases "computer science", "artificial intelligence" (except when part of a proper name)

  • articles ("a" or "the"), conjunctions ("and", "or", "but", etc.), or prepositions ("in", "of", etc.) in titles of articles or books
    • In such titles, when in doubt about what to capitalize,
      • either: only capitalize the first word,
      • or: capitalize the word that you're not sure about.

4.1.7. Apostrophes (')

• Don't use an apostrophe to form a plural, unless you are forming the plural of an abbreviation that might be misinterpreted otherwise.
  • For example, the plural of "apostrophe" is: apostrophes.

  • For example, the plural of OK (which, by the way is correctly spelled "OK" or "O.K.", but not "okay" and definitely not "Ok"!) is: OKs.

  • However, the plural of "A" is: A's (otherwise, it might look like the word "as" with a capital letter).

  • And the plural of a person's last name does not take an apostrophe:
    • "The Rapaports live here"; not: "The Rapaport's live here"
      • (The latter suggests that something that belongs to the Rapaports lives there.)

• Use them to indicate that one or more letters have been omitted from a word:
  • don't (= do not)
  • five 'n' ten (= five and ten).

• Use them to form the possessive: "Bill's book".
  • But this rule does not hold for possessive pronouns, none of which take apostrophes:
    • his, hers, yours, ours, theirs, its

• On "it's" vs. "its", see below

• Don't use "as" or "since" to mean "because".

• "Q: Does it matter, grammatically, whether I say "BECAUSE, SINCE or AS Sidney was leaving, his wife felt uneasy"?

  "A: Not grammatically because SINCE and AS are equated with BECAUSE. But AS is a poor choice, since AS also has a temporal sense. With AS, the example may mean either WHILE SIDNEY WAS LEAVING or BECAUSE SIDNEY WAS LEAVING. For the sake of clarity, use BECAUSE..." (Morton S. Freeman, "Word Watcher", Buffalo News (1999).)

• Avoid "as" at all costs:

  Here are some potentially ambiguous, real-life uses of "as":

  • "Exceptions might arise as changes to the rules are made."

    Does it mean:

    1. exceptions might arise while changes are made?
    2. exceptions might arise because changes are made?

  • "This set of sentences serves as the program's "brain" as the program deduces information."

    Does it mean:

    1. the set serves while the program deduces?
    2. the set serves because the program deduces?

  • "Model tracing is limited to a step-by-step diagnosis as the student interacts with the system on a single problem."

    Does it mean:

    1. tracing is limited while the student interacts?
    2. tracing is limited because the student interacts?

  • "As she is exposed to more of the text, we can query her regarding new inferences about[,] and inferences gained from[,] the reading. As we are interested in vocabulary acquisition, a single word from the tedxt is chose as the target unknown word [that] we wish to learn more about."
    • Here, there are two occurrences of "as". The first is used correctly in the temporal sense. The second is its use as a synonym of "because", which is best avoided.

    • Incidentally, the interpolated commas did not appear in the original text, but are needed, and the original text used "which" incorrectly, which I have replaced with "that", because this is a restrictive relative clause (see below).

  • "As" can also mean "to be" (short for: "as being", as in: "He was acknowledged as our leader after winning the election."):

    "These metatheories are acknowledged as some new approaches to developing intelligent tutoring systems basesd on these theories are currently under way."

    Does it mean:

    1. these metatheories are acknowledged because some new approaches are under way?
    2. these metatheories are acknowledged to be new approaches?
       This last reading is arguably impossible, but the example is a "garden-path" sentence [you're "led down the garden path" if you read "as" to mean "be"], and thus awkward in any case.

  • "As" can also mean something like "in the way that", as in "As Lincoln once said, you can fool some of the people all of the time":

    "Jabberwocky is a fitting text to analyze meaning recovery as it is most famous for its ability to convey meaning despite the vast number of nonsense words. As Alice describes the passage, "Somehow it seems to fill my head with ideas—only I don't exactly know what they are!" "

    • Here, the first occurrence of "as" should have been "because". The second occurrence is a correct use of "as" in its "in the way that" sense.

• And "since" has its own problems, because it has a temporal meaning. See:
  • Kilpatrick, James J. (2006), " "Because" Is Better, Because", Townhall.com (2 January).

• "would of" is always incorrect. It should be "would've" or "would have": "I would have gone with you."

• Ditto for "should have", "could have", etc.

• See: Safire, William (2008), "Of the Migrating Of", New York Times Magazine (13 January): 14.

4.2.4. "Their" vs. "they're" vs. "there":

• their = possessive of "they": "This is their car, not your car."
• they're = they are: "They're going to their car; I"m going to my car."
• there = at that location: "There's your car"
• For example, "They're going to their car, which they parked over there."
  • This means: They are going to the car that belongs to them, which they parked in that place.

4.2.4. "Try to" vs. "try and":

• Almost always, "try and" is incorrect; you should use "try to" instead.

• For example:
  • "Try and find out" literally means that you should attempt and then succeed to find out. But what if you can't find out?

  • What you should really say is: "Try to find out", which means that you should attempt to find out, but you may or may not succeed.

• Note that if you replace "try" by "attempt", you'll see that only "attempt to" (not "attempt and") makes sense.

4.2.5. "Which" vs. "that":

• A restrictive relative clause is a clause that "restricts" the noun phrase that it modifies. It is not eliminable.
  • For example, "The restrictive clause that is italicized in this sentence cannot be eliminated without changing the meaning of the sentence."

• A non-restrictive clause is a clause that does not "restrict" the noun phrase that it modifies. It is like a parenthetical expression that can be eliminated.
  • For example, "The non-restrictive relative clause, which is italicized in this sentence, gives you extra information that is a bit like an aside."

• Now for the point of all this: Use "that" to introduce a restrictive clause, and use "which" to introduce a non-restrictive clause.
  • Sometimes, you can use "which" to introduce a restrictive clause, though you shouldn't.

  • You should never use "that" to introduce a non-restrictive clause.
    • Here's a real example of why you shouldn't: "You have the option to submit a seperate [sic] $65 check for each child that you will get back when you work the concession stand." — Lou Gehrig Youth Baseball on-line registration form (2004)

      Presumably, what they should have said was: "You have the option to submit a separate $65 check for each child, which you will get back..."; i.e., you'll get the check back.

      Instead, they seemed to be saying this: For each child that you get back when you work the concession stand, you can submit a $65 check; i.e., you pay us $65, and we'll give you a child :-|

• Moreover, always precede the "which" that introduces a non-restrictive clause by a comma, and never precede the "that" by a comma.

4.2.6. "Your" vs. "you're":

• you're = you are: "You're going to the park; I'm not."
• your = possessive of "you": "Your book is red; mine is green."
• For example, "You're going to your car; I'm going to my car."
  • This means: You are going to the car that belongs to you, and I am going to the car that belongs to me.
• N.B.: These should not even be pronounced alike! "Your" is /yore/; "you're" is /yoor/.

4.2.7. "We" vs. "I":

• When should you use "we" and when should you use "I"? Many writers avoid "I", thinking that the first-person point of view is inappropriate in a formal paper.

• The academic "we" is certainly appropriate, but I think it's a bit stuffy. I'd use "I". You can also move between "I" and "we" as follows:

  • Use "I" when you really mean you and you alone. "In this section, I show that ..."

  • Use "we" when you're referring to you and the reader: "In this section, we shall see that ..."

Warren, Virginia L. (2001), "Guidelines for Non-Sexist Use of Language".