Writing Checklist

Reduce clutter and increase clarity of any document with these rules

Stanford MOOC on Writing in the Sciences

This writing checklist is mostly from advice in this massively open online course. You can take it yourself for free at your own pace.

Reviewing Writing

Whether it’s your own writing or someone else’s, keep all of these sections in mind as you go through this list.

- [ ] Run a spell checker.
- [ ] Get rid of unnecessary prepositional phrases -- author clearing throat (It can be shown that)
- [ ] Get rid of extraneous adverbs (very, really, quite, basically, generally)
- [ ] Get rid of there are / there is
- [ ] Get rid of extraneous prepositions (the meeting happened on monday -> the meeting happened monday) (they agreed that it was true -> they agreed it was true)
- [ ] Get rid of passive voice (is/was/are/were/be/been/am + past tense verb), replace with active voice
- [ ] Make sure to cite all images, methods, software, and empirical data. Review [the principles](https://www.force11.org/software-citation-principles) and try [CiteAs](https://citeas.org/about) if necessary.

Enhancing Clarity

As Shakespeare wrote in Hamlet, “Brevity is the soul of wit.”

- [ ] Be concise and direct.
- [ ] The use of "very" suggests that a cooler word exists, replace where possible.
- [ ] Make sure that articles such as "a" "the" "some" "any" and "each" appear where necessary.
- [ ] Ensure all subjects must match the plurality of their verbs ( no: "Apples is tasty" yes: "Apples are tasty").
- [ ] Recover verbs that were turned into nouns ("obtain estimates of" -> "estimates"; "provides a description of" -> "describes").
- [ ] Use the form <verb>ion of <noun> over <noun> <verb>ion. (For example, convert "calculation of velocity" to "velocity calculation".)
- [ ] Reduce vague words (important, methodologic).
- [ ] Reduce acronyms / jargon.
- [ ] Expand all acronyms on first use (rely on the acros.tex file and glossaries package to automate this).
- [ ] Turn negatives to positives (she was not often right -> she was usually wrong).
- [ ] Don't bury the verb (keep the predicate close to the subject at the beginning of the sentence).
- [ ] Refer to software consistently by name.
- [ ] When you introduce words or phrases that are unusual or likely to be unfamiliar to the reader, italicize them.
- [ ] If you use an uncommon word, either consider changing it or define it in its first usage.

Enhancing Style

You’re a human writing for other humans: Make the wording exciting, and remember some people reading it won’t know as much jargon as you do.

- [ ] Vary your sentence structure to keep readers engaged.
- [ ] Do not use contractions in technical writing.
- [ ] Use punctuation to help you to vary your sentence structure.
- [ ] Follow the convention that the power to separate in order of increasing power: comma, colon, dash, parentheses, semicolon, period
- [ ] In increasing order of formality: dash, parentheses, all of the others. Don't overdo the dash and parentheses
- [ ] Check that if there's a list in a sentence, it shouldn't come before the colon.
- [ ] Always use isotopic notation like `$^{239}Pu$`. Never `$Pu-239$` or `$plutonium-239$`.
- [ ] Strengthen up your verbs (use sparingly: is, are, was, were, be, been, am).
- [ ] Only use "large" when referring to size.
- [ ] Do not use the word "when" unless referring to a time (try "if" instead).
- [ ] Clarify or change misused/overused words where necessary (e.g., code, input, output, different, value, amount, model).
- [ ] Each sentence/paragraph should logically follow the previous sentence/paragraph.
- [ ] Examples should use variables instead of numbers and use symbolic math instead of acronyms.

Enhancing Grammar

- [ ] "Data" is plural (the data are critical).
- [ ] Compare to (point out similarities between different things) vs.  compared with (point out differences between similar things)
- [ ] Elemental symbols (Ni, Li, Na, Pu) are capitalized, but their names are not (nickel, lithium, sodium, plutonium).
- [ ] Do not use the word "where" unless referring to a location (try "such that" or "in which").
- [ ] Avoid run-on sentences.
- [ ] The preposition "of" shows belonging, relations, or references. The preposition "for" shows purpose, destination, amount, or recipients. They are not interchangeable.

Enhancing Punctuation

- [ ] Commas and periods go inside end quotes, except for when there's a parenthetical reference afterwards.
- [ ] Colons and semicolons go outside closed quotations.
- [ ] Semicolon: connects two independent clauses. OR separates items when the list contain internal punctuation.
- [ ] Use a colon to introduce a list, quote, explanation, conclusion, or amplification.
- [ ] The Oxford comma must appear in lists ("lions, tigers, and bears").
- [ ] Use hyphens to join words acting as a single adjective before a noun (e.g., "well-known prankster"), not after a noun (e.g., "the prankster is well known").
- [ ] Two words joined by a hyphen in title-case should both be capitalized.
- [ ] Hyphens join a prefix to a capitalized word, figure, or letter (e.g., pre-COVID, T-cell receptor, post-1800s); compound numbers (e.g., sixty-six); words to the prefixes ex, self, and all (e.g., "ex-sitter", "self-made", "all-knowing"); and words to the suffix elect (e.g., "president-elect").

Using Latin

- [ ] The Latin abbreviations viz., i.e., and e.g. should all have commas before and after them (e.g., "We can classify a large star as a red giant, e.g., Stephenson 2-18.").
- [ ] The Latin abbreviations cf., et al., or q.v. should not have commas after them.
- [ ] The abbreviation of *versus* (vs.) should always have a period in American English and is used to contrast things.
- [ ] You should never say "and etc.," because "et" already means "and" in Latin.
- [ ] Abbreviations including et (e.g., "et al.") should not have a period after "et" because it is a whole word.
- [ ] Some abbreviations, but not the majority, need to be capitalized (e.g., "N.B." which means "note well").
- [ ] Latin (or any Non-English) words, other than et, are usually italicized (e.g., *in situ, in vivo, in vitro,* and *ab initio*).

Tables and Figures

- [ ] The text should refer to all tables and figures.
- [ ] When referring to figures by their number, use `Figure 1` and `Table 1.` They should be capitalized and not abbreviated (not `fig. 1` or `figure 1`.)
- [ ] Align all columns of numbers in tables such that the decimals line up.
- [ ] All values should probably have the same number of significant digits in a single column.
- [ ] Give units for each numerical column.
- [ ] A table should have only 3 horizontal lines (no vertical lines and no more than 3).

Enhancing Math

- [ ] Define all variables, with units. If unitless, indicate that this is the case `$[-]$`.
- [ ] Subscripts should be brief and can be avoided with common notation. For example, `$\dot{m}$` is better than `$m_f$` which is superior to `$m_{flow}$`.
- [ ] Variable names should be symbols rather than words `m` is better than `mass` and `\ksi` is better than `one_time_use_variable`.
- [ ] The notation `$3.0\times10^{12}$` is preferred over `$3e12$`.
- [ ] Equations should be part of a sentence.
- [ ] Equations should be in the `align` environment. Align them at the `=` sign.
- [ ] Variables should be defined in the `align` environment as well, not buried in paragraphs.

Here’s an example of an equation:

The line is defined as
\begin{align}
y&=mx + b
\intertext{where}
y&= \mbox{ height of the line, also known as rise [m]}\nonumber\\
m&= \mbox{ slope [-]}\nonumber\\
x&=\mbox{ independent parameter, known as run [m]}\nonumber\\
b&= \mbox{ y intercept [m].}
\end{align}