Skip to content

Latest commit

 

History

History
206 lines (155 loc) · 14.9 KB

improving-your-writing.md

File metadata and controls

206 lines (155 loc) · 14.9 KB
Raw

Academic writing

Companion documents: Formatting your work, Improving your writing, Making a figure, Responding to reviewers

Why should I read this?

Many students have trouble producing scientifically acceptable writing without significant training. (I use "scientifically acceptable" as a suitcase word for whatever seasoned academics find appropriate in journal papers.) Perhaps this isn't surprising; students do not formally learn how to do this.

This is juxtaposed with just how important your writing is. You likely will only remember some details of your past research projects. Instead, you'll be able to use your papers as references. Other scientists won't see your research notes (nor would you want them to) or know the details of your academic past. Instead, they will judge you based on your archived writing (conference proceedings and journal articles). Only a few opportunities exist to side-step this. Giving conference and invited talks communicates your research without paper-in-hand. However, this format is ephemeral. Anyone interested in your talks can find your papers to understand your contributions without time constraints. It is also two-way coupled: you likely will only find yourself invited to give talks with the presumption of good papers behind them.

Careful writing also begets careful thinking (and vice-versa). That is, forcing yourself to clarify and organize your work will bring problems in your thinking to light. Because of this, improving your writing as soon as possible can be useful. New students may well be over a year from starting a manuscript for a journal. However, they, too, will benefit from carefully writing up their notes, ideas, and plans.

For the above reasons, high-quality scientific writing is often expected from students ready to graduate with their Ph.D. I invite you to use this document to bootstrap your way to scientifically-acceptable technical writing.

From a now-deleted StackExchange post on "pet peeves in academic writing":

Ernest Hemingway wrote that "the only kind of writing is rewriting." E. B. White wrote essentially the same thing: "The best writing is rewriting."

I have plenty of pet peeves about academic writing, but they all seem to have the same cause: that the author apparently didn't care about writing well.

Your first version of anything is likely to be mediocre. (That's certainly true for me!) Care about your own writing, enough to notice and be annoyed by shortcomings in your first draft, and then figure out how to improve it. Do this, and you will be well on your way to excellent writing.

Also see: Does writing matter a lot in research?

Automatic grammar, spelling, and syntax checkers

Several of these exist. I use Grammarly. It offers are free tier and a trial of the "pro" service at the time of writing. I purchased the full Grammarly and do not regret the purchase.

These tools can check for simple things, like improper spelling and grammar. They can also identify more complicated style-related things, such as active and passive voices, repeated words and sentence-starters, "sticky sentences" (run-on sentences held together by many articles), and so on.

I recommend using one of these before submitting any paper or abstract. Often, even seemingly obvious mistakes can go unnoticed after so many revisions. Such mistakes are a quick way for an editor or reviewer to perceive your work as careless (e.g., does he conduct his simulations like he writes his abstracts?!), even if only subconsciously.

Consistency

One should keep styles consistent within a manuscript. You might be forgiven for even poor style choices if you are consistent. Please look at the these documents for more.

Nomenclature

Changing technical terms mid-way through a paper in the name of style will confuse people. If your domain is a cylinder, don't switch to "tube" at any point. If you call your model a "physical model," do not switch to calling it a "numerical model" (with the additional problem that these two things aren't the same, anyway). If you define your “mesh spacing” in one section, don't switch to "grid spacing" or "mesh resolution" later on.

Concise writing

One should prefer using as few words as required when describing something technical. You can consult replacement lists for common mistakes:

These lists are a way of realizing, "Hey, I write wordy phrases like this all the time!". Use the lists to learn the general ways one ends up with low information-density writing. You can then identify similar phrases in your writing. Often, eliminating them is relatively easy, but noticing them is (at first).

Conciseness can be viewed in a broader sense. For example, you should structure your paragraphs such that you aren't repeating information. Other tips of this type are available at these links:

What goes where

Always have a narrative first figure that demonstrates what you are doing and "tells the overall story." Take time to make this figure as attractive as possible. It is one of the first things your readers will see! See, for example, the first figure in my paper "Fast Macroscopic Forcing Method."

  • Abstract
    • Include a full, self-contained, mini-version of your paper. This includes an introduction to the method you use, quantitative measures of your results, and your final conclusion and takeaways.
  • Introduction (in this order)
    • What is your work?
    • Why are you doing it?
    • What is the open problem you are trying to solve?
    • What are some methods related to your work?
    • What key contributions will you add? (without full detail)
    • What does the rest of the manuscript contain?
  • Acknowledgments
    • Always have an unnumbered acknowledgement section before the references but after the discussion/conclusions. This is where we acknowledge funders and those that have helped with the work but are not authors.
  • Future work
    • I recommend not including a future work section in your papers or presentations

Guidelines, tips, and more!

Things to avoid; from the Angry Reviewer

  • Don't hype. Avoid words like novel, highly, clearly, greatly. Better still, avoid all adverbs.
  • Don't use clichés. In a nutshell, by and large, they are clear as mud.
  • Don't use "very" very often. Usually, there is a better word for it.
  • Be concise. Avoid phrases like "by means of, despite the fact that, in order to".
  • Avoid negatives. For example, use "unable" instead of "not able".
  • Avoid redundancy. For example, use "investigate" instead of "conduct an investigation of".
  • Use active voice. Although not always possible, most of the text should be in active voice.
  • Avoid inappropriate language. Keep words like "really, actually, pretty much" for social networks.
  • Avoid rare words and latinisms. Non credo all readers know the meaning.
  • Keep abbreviations to minimum. Abbreviations are hard to read, consider just spelling it out.
  • Beware of zombie nouns. Utilization of nominalization is causation of distraction.

From some tips for scientific writing

  • Use the "show don't tell" technique. If something is interesting or surprising, the reader should be interested or surprised by what they've read. They shouldn't need to be told. Anton Chekhov reportedly said: "Don't tell me the moon is shining; show me the glint of light on broken glass".

  • Don't bury the lede. When journalists write articles, they usually put the crucial information in the 'lede' opening paragraph. Hiding big news later in the piece is known as "burying the lede". This idiom forms part of the inverted pyramid approach to writing: put the most important information first in an article or section, then fill out the details.

  • Read widely, reflecting as you go. Why was that sentence hard to follow? Why did you like that section of text? Why was that turn of phrase annoying? What gave that paragraph its nice balance and rhythm? As Toni Morrison once put it: "Writing is really a way of thinking – not just feeling but thinking about things that are disparate, unresolved, mysterious, problematic or just sweet."

  • Make your reader care about what they're reading. Like a good story, that typically means outlining a clear problem, with the promise of a later resolution.

  • The analysis wasn't done by some anonymous entity. You did the analysis. So avoid the passive voice if possible. (See also: "a decision was made" rather than "we made the decision" when it comes to responsibility-dodging in leadership messages.)

  • If you promise something in the introduction, make sure you've delivered by the end of the results. For example, if you open by mentioning A and B, readers will be expecting a conclusion about A and B by the end of the paper. "Remove everything that has no relevance to the story,' as Chekhov put it. "If you say in the first chapter that there is a rifle hanging on the wall, in the second or third chapter it absolutely must go off."

  • Follow Orwell's rules of writing

    • Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
    • Never use a long word where a short one will do. If it is possible to cut a word out, always cut it out.
    • Never use the passive where you can use the active.
    • Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
    • Break any of these rules sooner than say anything outright barbarous.

  • Kill your darlings. Sometimes you'll write a phrase that is so elegant and so well crafted, it jars with the rest of your writing and pulls the reader out of the flow. So cut it. As Stephen King once put it: 'Kill your darlings, kill your darlings, even when it breaks your egocentric little scribbler's heart, kill your darlings.'

  • If you want to describe a figure/table in the results text, it can help to imagine you're giving a seminar. What features would you draw your audience's attention to? What would you tell people about in the coffee break?

  • Help the reader interpret your figures and tables. Don't give them a sixteen panel graph and expect them to spot the main takeaway; if the author can't be bothered to find a key message, the reader almost certainly won't either.

  • You can probably cut about half your word count if you really need to do, without losing your meaning. (I've managed to cut down a bunch of paper submissions into much shorter report formats when really pressed.)

  • A good intro and discussion will often include a reference or statistic most readers won't have been aware of. Try and find the best references, rather than the easiest ones.

From Koen Hufkens

His document covers a small subset of components of a well-written manuscript. Some of these are soft writing rules/guidelines. They can be broken, but one usually has to understand why they exist in the first place before breaking them. If you are consciously breaking a rule in your view for a good reason, then go for it. Otherwise, stick to the guidelines.

  • Use active language
  • Avoid long sentences
  • Simplify your language (no thesaurus)
  • One paragraph communicates one important idea
  • Connect paragraphs and ideas in a logical order
  • Use the present tense for the main part of the manuscript; past tense is allowed in some parts of the abstract and conclusions.
  • Avoid informal language
  • No superlatives (e.g., very complicated)
  • Limit the use of conjunctive (connecting) words (e.g., however, moreover). It's ok to just start a sentence!
  • Limit repetitive words (don't substitute using the thesaurus, re-evaluate the sentences)
  • Don't use spoken contractions (e.g., it's)

Required watching

Before writing a paper, watch these two lectures from the University of Chicago:

Other links

Over the years, I found the documents below helpful for improving my writing: