Statlab's Home Page || N. Heckman's Teaching Page || N. Heckman's Home Page ||  

TECHNICAL WRITING CHECKLIST
Nancy Heckman



Comments/additions welcome

Have you used a spell-checker?

Have you properly proof-read your work before submitting it? This means leaving the writing for a bit - a few hours or a day - and then carefully reading a paper copy (not on-line) with fresh eyes, not tired eyes. Look carefully, reading what is on the page, not what you remember being on the page.

Have you properly motivated your work? Mathematical equations don't serve as motivation! Here is an example of a motivation. ``Several authors have studied estimation in the partially linear model with independent errors (references). But so far, no one has considered the partially linear model with dependent errors. This modification of the model is necessary for analysis of pollution data, which are typically time series."

Is what you've written ambiguous? Will the reader know what you mean by "it"? It's OK to repeat words. See above - the repetition of "partially linear model", as in "no one has considered the partially linear model with dependent errors" as opposed to ``no one has considered it with dependent errors". The former is easier on the reader.

Is your writing precise? "Data are transformed because of numerical instability" is vague. Better "Data are transformed to increase numerical stability of the computation of estimates." Oops, these sentences are in passive voice ... Change to active" "I transformed the data ..." However, passive voice isn't too bad here since "Data" are the focus of the sentence.

Have you used shorthand that might confuse the reader? "Estimate the model" isn't clear. Instead write "Estimate the parameters of the model".

Have you explained your equations? Nothing is worse for the reader than a solid page of equations with no text. Before and after every group of equations, write some words about what you are doing. "Using the strong law of large numbers to study the first term in the bias expression ... equations equations .... The last equality follows by the bound on the variances, as assumed in condition 3.2." This will help the inexperienced statistician know the main points and will also allow the knowledgable reader to skim the equations.

Do you make good use of equation and theorem numbers? Bad: "as assumed somewhere in section 3". Better: ``as assumed in condition 3.2". How should you number equations and theorems? This may depend on the length of your paper. The default in latex is that equations are numbered (1), (2), ... and this may be fine for short papers. For longer work, consider numbering equations and theorems by section/chapter so that they can be more easier located by the reader.

Have you used a similar argument/calculation over and over in your proofs? Consider translating the repetitious result into a general statement, in the form of a lemma.

Is there some general notation/explanation that will serve for several models or data sets or ..? Usually, it's better to put the general information in one section, rather than embedded throughout several model explanations.

How is your notation?

  • Is your notation internally consistent? When you call the sample size n in Section 1, do you switch to m in Section 2? Bad! Do you use the symbol n for something else in Section 3? Bad!
  • Have you built up your notation in the course of your arduous work and are now "married" to it? You can easily end up with some very ugly notation that you have gotten used to, notation that no reader will ever get used to. Change it! Useful latex hint: use \def or \newcommand to define your notation. Then you can change it easily and consistently throughout the manuscript by just changing the \newcommand definition.
  • You can use \def or \newcommand to help make your proof-reading/writing/editing of complicated equations much easier. Define any boldfaced symbol or a symbol with bar, hat, tilde etc, eg \def\xbar{{\overline x}}.
  • Is your notation consistent with the literature? Is there a much-referenced paper that has established common notation? If so, use this notation. Is your work based on an obscure paper with horrible notation? If so, change the notation!
  • Are your fonts consistent and clear? For instance, if you use bold for vectors, have you done so throughout? For instance, do you use $\bf{l}$ (el) and ${\bf{1}}$ (one) as the two symbols are very similar.
  • Usually, one doesn't begin a sentence with a symbol.

    • Are your tenses consistent? You shouldn't write "The authors proved a=b. They show this by ....". The first sentence is in the past, the second in the present.

    Have you written things in your own words, rather than copying from your a reference directly? If you copy something directly from other material, you must put it in quotation marks and name the source. However, such direct use of other material is very unusual in scientific writing. Use direct copying only for a very brief quote that is so brilliantly worded, that the reader will enjoy seeing it exactly as originally written. (example??) Otherwise, you should write the information from the reference in your own words and your own notation. And you should give the proper reference for the content.

    Have you sat back and looked at your proof/analysis, to see what parts are irrelevant, to see how it can be streamlined? Typically, the first way you prove something is not the best. The first proof is just how the algebra happened to come out of your brain. After you see the proof, can you see the main parts of the algebra/calculations? For instance, perhaps one term converges to zero and another term converges to a standard normal. Breaking the proof into these two ideas helps the reader understand. A good, easy to read proof is linear: first a then b then c, so the reader's eye and brain move down the page. For data analysis, you often make a lot of plots to figure out what type of analysis to carry out. You don't need to include your entire thought process in your write-up. Which plots are relevant?

    Have you checked your reference list? Typically, a journal or graduate program will have a preferred bibliography style, and you can implement this in latex, with a bibtex bibliography file that lists all of your references, and allows you to cite each easily within the text. This makes your life easy.

  • When you construct the bibtex file, be sure to let latex know if the item is a journal article, a book, or ... This allows latex to automatically format the reference entry (e.g.~book titles will get capitalized appropriately).
  • Be careful: Latex will typically not capitalize everything wat you have capitalized. It follows rules, depending on the bib style you are using. For instance, some latex bib styles only capitalize the first word in a journal article title. So words like Bayesian and Markov will not be captialized. To force the capitialization, you must write {B}ayes or {M}arkov.
  • Be sure to update your reference list. Has that archive article been accepted? Update the reference! Think how, if the author reviews your work (as a paper reviewer or as the external reviewer on your PhD thesis), how the author will feel about having to correct you.
  • For citing in the text, be careful of using \cite or \citep. For instance, my pet peeve is seeing "for smoothing (Wahba (1984))". Too many parentheses! It should look like "for smoothing (Wahba, 1984)".

    Have you used passive voice? Passive voice tends to be indirect and wordy. Active voice engages the reader in your thoughts. Active voice's directness is what one expects in scientific writing. If you see you've used passive voice, can you easily change it to active? Most of the time you can.

    The royal we: The "royal we" occurs when one person refers to themself in the plural as in "we woke up this morning", when you would usually say "I woke up this morning". The name comes from the fact that kings and queens refer to themselves as "we". Writers in most disciplines do NOT use the royal we. When they are the sole author on a paper, they write "I did this." In statistics, you will find use of the royal we. Some statisticians avoid the use of "I", but instead use "we" or the passive voice. You may want to make your own decision here, or discuss it with your supervisor. Note: "we" in a paper can refer to the author and the reader. This isn't the royal we. "We can consider ...."