my writing tips

Some (opinionated) tips on writing papers and reports.

I have read a fair few papers and reports in my time. If you are one of my students, then you may use the following list of common errors, thoughts and tips to decipher the scribbles that I have put on your work. Thanks to my advisor Dave for many of these tips. Also see Dupré, Bugs in Writing; while our library does not have a copy, you could try an ILL or you can peruse the copy in my office. I have links to other writing tips elsewhere.

  • [#AC] Define acronyms and initialisms when first used.

  • [#AM] Ambiguity. Don’t say ‘This is fast’, say ‘This widget is fast’ - the reader may not know what ‘This’ refers to. See also #AV.

  • [#AV] Use the active voice, not passive. The passive voice indicates that the subject has had an action ‘done’ to it. This obscures who actually did it. It is much better to be explicit about what you have done (especially if you are a student who wants to receive credit for it!). So please use the active voice: ‘I built a widget’ rather than ‘the widget was built’.

  • [#BI] Make sure your bibliography has been proof read and is consistent. Include enough information to help the reader find the paper; if it exists, a DOI or URL is essential. See also The devil’s guide to citing the literature. Check your capitalisation if using BibTeX and put brackets around words that need manual capitalisation, e.g. ‘the {Internet}’ or ‘{Wi-Fi}’. Do not assume that you can automatically import .bib files from a number of publishers or sources; they are all inconsistent so you will need to go through and make sure that everything looks coherent. That said, Crossref DOI content negotiation can provide a useful starting point; try e.g. curl -LH "Accept: text/bibliography; style=bibtex" https://doi.org/10.1145/1764873.1764887. I like to use BibTool for tidying everything up.

  • [#BT] Make sure your LaTeX quotation marks look like `this' and not 'this'. The backtick is significant.

  • [#CA] Compound adjectives: compound words that are used as adjectives need to be hyphenated. So ‘well-known algorithm’ rather than ‘well known algorithm’. The latter means ‘well (known algorithm)’ which may not be the intent. An exception is if the compound adjective starts with an adverb, such as ‘the overly used algorithm’.

  • [#CN] Citations are not nouns. Do not write ‘[4] shows that blah’. Write ‘Bloggs et al show that blah [4]’.

  • [#CO] Commas are tricky. Perhaps the most common error I see is the comma splice. But various other comma errors exist, so please proof read. Unlike some, I hold no strong opinion about the Oxford comma.

  • [#CT] Don’t use contractions (such as ‘don’t’) in formal writing.

  • [#DT] Is ‘data’ a plural or a singular noun? I believe that it is a plural, but I accept that I am increasingly in the minority. Please be consistent (this is a running theme in many of these tips). Here is an interesting blog post on this topic.

  • [#FM] Footnote marks go after punctuation. Like this.1 Not this2.

  • [#HW] Do not put ‘however’ at the start of a sentence. ‘However, our results are limited because of a meteor strike’ should read ‘Our results are limited, however, because I didn’t have time to finish the experiments before the paper deadline but somehow thought that a meteor strike would be a more plausible excuse’.

  • [#IE] i.e., e.g. and etc. are often misused. It can be useful to think of the Latin terms that these terms abbreviate. id est roughly means ‘that is’, exempli gratia ‘for example’ and et cetera ‘other similar things’. This oatmeal comic is good on the use of ‘i.e.’ and ‘e.g.’. This Grammar Girl column offers some tricks to remember the correct usage. Note that in British English ‘e.g.’ is not followed by a comma, but it is in American English. I don’t mind which you use, but it is important to be consistent.

  • [#NB] Use a non-breaking space when you don’t want something to appear at the start of a new line. So in LaTeX, use a tilde as appropriate, for instance discussion about evidence~\cite{bloggs:paper} or In Figure~\ref{fig:result}.

  • [#PC] Punctuation. One common error that I see is the misuse of semicolons; you can typically use these for lists, or to join connected but independent clauses. See Merriam-Webster for a clearer description. Conversely, a colon is typically used to introduce an explanation. Also see [#CO].

  • [#QT] Single and double quotation marks have almost completely opposite usage in American and British English. I don’t mind which you use, but please be consistent. This Grammar Girl column goes into lots of detail about quoting.

  • [#RI] Reduce ink in diagrams. See VQDI by Tufte; I have a copy in my office but there are lots more in the library.

  • [#SP] Spell-check. Use a spell-checker, but you should also proof read to catch those all too common errors such as ‘it’s’ instead of ‘its’, ‘loose’ instead of ‘lose’, or greengrocer’s apostrophes.

  • [#TH] Think about the ‘take-home’ point of any image or figure that you include. That is, what is this figure telling the reader? For instance, if you have a CDF plot of various sets of measurements, be explicit about what conclusion you want the reader to take home with them (That one distribution is higher than the other? That there is a particular knee in the curve caused by performance improvements in your system?). I always suggest that my students include a one-sentence summary of this take-home point in the caption. A picture is worth a thousand words, but the author’s thousand words may differ from the reader’s. It can thus be useful to be explicit. Conversely, if you cannot think of anything interesting to say about a figure, delete it. The same applies to slides in presentations.

  • [#TI] ‘The Internet’ should be capitalised. I appreciate that this is controversial (indeed there is a whole Wikipedia page about it). But in a computer science paper talking about the Internet protocol reference model based on IP, you must use the ‘Internet’ because this is only one instance of an internet (that is, a network of internetworked computer networks).

  • [#TP] Paragraphs should begin with a topic sentence that introduces the main idea of that paragraph. For a paper this might often be the finding that you are discussing.

  • [#TS] Tenses can be tricky in scientific writing. This article from Nature is quite good on tenses as well as some other writing issues. But in short: use present tense for findings that you believe are still true (for instance when discussing related work). Use the past tense to report on what has happened (for instance what you did). Use the future tense to report on what will happen (for instance your proposed future work).

  • [#VB] Verbosity. Conciseness makes your writing clearer (and so can make it easier for you to obtain appropriate credit or marks). Phrases such as ‘in order to’ can be reduced to ‘to’. Try not to repeat yourself. At the same time, be specific. Don’t say ‘the algorithm was very fast’; ‘very’ rarely adds anything. Say how fast it was.

  • [#WT] Which, who and that. ‘That’ is used for restrictive relative clauses, i.e., a clause that restricts the meaning. For instance, in the sentence ‘The module that I took was all about networks’, ‘that’ is used to restrict and specify a particular module. Whereas in ‘The module, which was so incredibly interesting, was all about networks’, ‘which’ does not restrict, and is surrounded by parenthetical commas because it is not essential to the sentence. So ‘which’ is used for non-restrictive clauses, as is ‘who’. You can find lots of detailed information about this elsewhere on the Internet, for instance at Purdue.