View source for Small comments on papers

This page collection together a list of "standard" small comments that I have on papers, with the hope that students and other co-authors will read it ahead of time and address some of these before sending me something to read.  Many of these are idiosyncratic and the lead author on a paper has the final say, but since I make them over and over again, I figured I would start to write them down.

=== Top Ten Most Common suggestions ===

# Google "which versus that".  If the word "which" doesn't have a comma before it, you probably got it wrong.
# All technical documents, even a draft paper, should have a title, authors, and “identifying information” (current date or “Submitted, 2017 Winter q-bio” or something similar).
# Get rid of acronyms unless you use the acronym when speaking about the term (eg, DNA is fine)
# Never use an equation number on its own; the equation number is an adjective, not a noun (so "(19)" should be "equation (19)" or "system (19)")
# Punctuation equations as if they were part of the sentence
# Typeset the math right: ||x|| << 1 is typeset in LaTeX as <tt>$\| x \| \ll 1$</tt>, which will come out as <math>\| x \| \ll 1</math> instead of <math>||x|| << 1</math>.
# Don’t use contractions in formal writing
# Use display style (e.g. equation or displaymath) for typesetting mathematical expressions that are taller than the standard text
# Definitions should be set in regular (non-italics) font with the defined term ''italicized''.  Remarks and examples should be in normal (non-italics) font.  Theorems are italicized.
# Read [https://doi.org/10.1137/1.9780898719550 Higham's book] on writing for the mathematical sciences.

(more to come)

=== Other suggestions ===

* You should update the abstract so that it works as a “standalone” description of the *results* of a paper.  Remove terms like “in this paper” that aren't really useful.  Keep the introductory comments to a minimum (once sentence should be enough) and focus instead on summarizing the contents of the paper.

* I’m not a fan of the word “surprisingly” (or “interestingly”) in papers.  Let the reader determine whether they are surprised.  So perhaps change “surprisingly simple expression” to “simple expressions” (note also the plural).

* "an holistic” → “a holistic” (at least in American English)

* "well behaved” → “well-behaved” (more generally, multi-word phrases that are "converted" to an adjective are usually hyphenated.  So "it was well behaved" and "well-behaved response".

* I am not a fan of acronyms except when they are used in common speech.  I think when you talk about sequestration feedback systems you say “sequestration feedback systems” and not “ess eff bee”.  Assuming that is correct, “SFB” → “sequestration feedback systems” (globally).

* "Section 2.2 and section 2.3 uses” → "Section 2.2 and Section 2.3 use”: the term "Section" should be capitalized and make sure that your verb agrees with the subject properly.

* Figure 1 is about 2X too big.  As a guide, the text in a figure should be roughly the same font size as in the caption.

* As a general note on the introduction: it would be good to say more here about previous work on feedback circuits, fundamental limits, and how this work relates.  Right now, it seems like there is only 1 paper that has ever done work in this area.  Remember that some of the people whose work you are not bothering to cite as relevant prior effort are likely reviewers of your (eventual) paper.

* When you refer to a figure in the text, use the same term and capitalization as appears in the caption (so Figure 1, not fig. 1).

* I’m not a huge fan of the term “plant” for the process that is being controlled.  OK to use this, but perhaps explain it since not all readers will necessarily know what you are talking about (especially when there is something else called a “plant” in biology, with a bit of a longer history of usage).

* I was always told to avoid starting sentences with lower case letters (even when they are a math symbol). It is confusing to the reader, since we use the capital letter to help us find the start of a sentence. Rewording can usually fix this problem.

* There appear to be several places where latex is putting extra space after a period.  You can fix those by using “.\ “ when the period is not the end of a sentence (eg, in “et al.” or “eqs.”).  Another approach, if you want to avoid a line break, is to use a tie (~): “.~(\ref{eqref})”.

* There are several spots where you assume your reader knows more than he/she might.  For example, you talk about the sensitivity function without giving a citation for people who might not know what you are talking about.  Same for Bode’s integral theorem.

* The right way to get the symbol for a norm is $\| x \|$ not “||”.

* Some of the text in Figure X is too small (especially the legend in panel B).  As a guide, the text in a figure should be roughly the same font size as in the caption.  You can probably go 1 pt size smaller, but I wouldn’t go below that.  Also, looks like you might be using png/jpg for the figure?  Better to use PDF since it will use vector graphics => doesn’t get blurry when you zoom in.

* The right way to get “<<“ is to use \ll (and \gg for “>>”).

* Equation (9) is missing punctuation (good job on catching it most other places!).  As a general rule, punctuation inline and displayed equations as if they were text.

* The body of a theorem or proposition should be italicized.  The body of a remark should not be.  For a definition, only italicize the defined term.

* Expand “iff” to “if and only if” (unless you say “iffff” when you read it aloud).  Similarly, write out "for all" and "for every" when it appears in body text.  OK to use symbols ($\forall$ in an equation.

* I’m starting to get annoyed by references to supplementary information that seem relevant to me understanding the material.  Is there a reason to relegate results to something that nobody is going to read?  I would really only use SI (ess eye) for supporting information that is there to show some level of detail that would detract from the main flow of the paper.

* Consider using a style that uses a smaller font for captions than for the main text.  This makes it easier to separate these (I got confused on page 12, where it looked like the equations were part of the caption for a second).

* Check for consistent capitalization in the figure titles.

* For references: you should either put full names everywhere or use initials everywhere (I recommend the latter).  Also, I strongly encourage the listing of references in alphabetical order, since that makes it easier to find a reference to a specific paper.  In the end this differs by journal, so OK to leave this like you have it, if you prefer.

* For citations, there should be a (non-breaking) space before the citation number [5].  In LaTeX, use the tie (~) to create a non-breaking space.

* “e coli” should be “E. coli” (italicized)

* The terms “in vivo” and “in vitro” should be italicized

* For references that are not available via a publisher, you should give a DOI (if available) or URL to the paper.

* When typesetting subscripts and superscripts, if the subscript is an abbreviation or shorthand for a word (or words), then it should be typeset as text, not math.  So <math>x_\text{d}</math> (where 'd' is for 'desired'), but <math>x_i</math> if <math>i</math> is an index variable.

* Then defining abbreviations, don't capitalize the terms unless they would ordinarily be capitalized.  So "simultaneous localization and mapping (SLAM) algorithms", not "Simultaneous Localization and Mapping (SLAM) algorithms" and "hidden Markov model (HMM)".