How to write papers so people can read them

Written by your-uid-here (your-name-here)
Published: 2016-09-17 (last updated: 2016-09-18)

Explaining your work is a big part of becoming a successful researcher.

The lack of technical sophistication is not the first factor of difficulty in reading PL papers. The first factor is that many papers are poorly written.

The question the reader would like an answer to is: what does it do, and why should I care?

There are principles that you can follow, based on how readers process information.

These principles are constructive: if your paper doesn't follow them, they tell you how to transform to make it follow them.

Flow

It should be clear how each sentence and paragraph relates to the adjacent ones.

To achieve that, follow the "old to new" principle: begin sentences with old info and end them with new info. Also emphasise new information.

But flow is not enough! You can have great flow but be completely incoherent.

Coherence

It should be clear how each sentence and paragraph relates to the big picture.

A paragraph should have one main point, expressed in a single point sentence.

Other principles

  • "Name your baby": give unique names to things and use names consistently
  • "Just in time": give information precisely when it is needed, not before.

Structure of a research paper

A structure that works:

  • abstract (1000 readers)
  • Intro (100 readers)
  • Main ideas (50 readers)
  • Technical meat (5 readers)
  • Related work (100 readers)

CGI model for an abstract/intro

  • Context: set the stage, motivate the general topic
  • Gap: Explain your specific problem and why existing work does not adequately solve it
  • Innovation: State what you've done that is new and explain how it fills the gap.

Alternative opinion: Simon Peyton-Jones advises to eliminate Context, e.g. "Consider this Haskell code…". If this works, it can be very effective, but I find it doesn't often work.

Main ideas section

  • Use concrete illustrative examples and high-level intuition
  • Do not show the general solution (keep it for the technical section).

Related work section

  1. It should go at the end of the paper. You can only properly compare to related work once you've explained your own.
  2. Give real comparisons, not a "laundry list"! Explain in detail how your work fills the gap that related work doesn't.


Q&A

Q: Do you have advice about paper titles?

A: It's certainly very important and I spend a ridiculous amount of time on them, but I don't have constructive principles about them yet.

Q: How much time should one spend on each section?

A: In my opinion, the amount of time should be proportional to the expected number of readers (see above).

Q: Any tips for turning a paper into a presentation?

A: Sorry, that would need a whole presentation!


Useful related books

Style: Toward clarity and grace. Learn technical writing in two hours per week. Simon Peyton-Jones, How to write a great research paper.