I keep forgetting lessons about writing. After writing a text, my usual response is to declare it as near perfect and never look at it again. In this text, I will describe a checklist, which I can use to quickly debunk the declaration. I plan to improve this checklist over time. Hopefully, text which passes the checklist in a few dozen years from now will, indeed, be near perfect.
The list is roughly ordered by importance. The text should:
Ensure that the writing is valuable to the community of readers.
Be simple (Adams, 2015) or be made as simple as possible, but not simpler[1]. This is also known as Occam's razor, kill your darlings or the KISS principle.
Be polite, that is, not contain a career limiting move. For example, do not "write papers proclaiming the superiority of your work and the pathetic inadequacy of the contributions of A, B, C, ..." (Wadge, 2020).
Be consistent. For example, either use the Oxford comma in the entire text or do not use it at all.
Avoid misspellings.
Avoid comma splices.
Place the object before the action, so write "the boy hit the ball" instead of "the ball was hit by the boy".
Flow naturally; just like a normal conversation. This is, for me, contradictory to writing when programming.
Provide a high-level overview of the text. This can be a summary, abstract, a few sentences in the introduction or a combination of these.
Prefer common collocations. A list of common collocations is The Academic Collocation List.
Use simple verbs, for example, prefer "stop" over "cease to move on" or "do not continue".
Avoid dying metaphors such as "stand shoulder to shoulder with" (Orwell, 1946). Metaphors aim to "assist thought by evoking a visual image" (Orwell, 1946). Dying metaphors do not evoke such an image anymore due to overuse (Orwell, 1946).
Avoid pretentious diction such as dressing up simple statements, inappropriate adjectives and foreign words and expressions (Orwell, 1946). For example, respectively "effective", "epic" and "status quo" (Orwell, 1946).
Avoid meaningless words, that is, words for which no clear definition exists. For example, "democracy" and "freedom" have "several different meanings which cannot be reconciled with one another" (Orwell, 1946).
In programming, one of the main goals is to avoid code duplication. Code is deduplicated by introducing functions. This deduplication is good, but can introduce functions which meaning can only be explained as a helper for deduplication. For example,
f("A")
g("A")
f("B")
g("B")
...is replaced by
process(s) = f(s); g(s)
process("A")
process("B")
...Programmers are used to these kind of functions. However, outside of programming duplication is allowed if it improves readability. Synonyms should be used to avoid boring the reader with the duplicates.
| [1] | This statement is likely to be attributed to Einstein (Quote Investigator, 2011). |
Orwell, George (1946). Politics and the English Language. Retrieved July 29, 2020, from https://www.orwell.ru/library/essays/politics/english/e_polit
Adams, Scott (2015). The Day You Became A Better Writer. Retreived April 23, 2021, from https://www.scottadamssays.com/2015/08/22/the-day-you-became-a-better-writer-2nd-look/.
Wadge, B. (2020). The Secret of Academic Success – or fun filled failure if you prefer. Bill Wadge’s Blog. Retrieved July 29, 2020, from https://billwadge.wordpress.com/2020/02/06/the-secret-of-academic-success-or-fun-filled-failure-if-you-prefer.
Quote Investigator. (2011). Everything Should Be Made as Simple as Possible, But Not Simpler Retrieved July 29, 2020, from https://quoteinvestigator.com/2011/05/13/einstein-simple/