Writing

Table of Contents


Required reading

Recommended reading

Key concepts/skills/etc

Pre-quiz

Please go to the Grattan Institute website and look at the report: ‘No free lunch: Higher super means lower wages’: https://grattan.edu.au/report/no-free-lunch/. Please also download the report itself: https://grattan.edu.au/wp-content/uploads/2020/02/No-free-lunch-Higher-superannuation-means-lower-wages.pdf. By way of background, superannuation is a scheme whereby the Australian government forces all workers to save for their retirement. It is currently 9.5 per cent of your wage, and it is planned to increase to 12 per cent in a few years.

  1. Title: Please read the title of the report. What is good about the title and what could be done better? How many marks would you give the title out of 3?
  2. Abstract: Please read the ‘abstract’, which is the main content in the webpage: https://grattan.edu.au/report/no-free-lunch/. What is good about the abstract? What could be done better? What mark would you give them out of 5 and why?
  3. Introduction: Turning to the report itself (the PDF), what do you think of the ‘Introduction’ (they call it an ‘Overview’)? What is good about it and what could they have done better? What is the main difference between their ‘abstract’ and their ‘introduction’? What mark would you give them out of 5 and why?
  4. Dataset: Please look at pages 21 through to 32 (and any other pages that you need - the appendices may be useful). To what extent have they explained their dataset? Where have they done well? What could have been done better? What mark would you give them out of 10 and why?
  5. Model and results: Please look at pages 32 through to 37 (and any other pages that you need - the appendices may be useful) and examine their models and results. Do you understand the model? How could they have done better? Do you understand their results? Again, how could it have been done better? Do you think that they have satisfied the assumptions of the model that they are using? Finally, do you understand the weaknesses of the model? What mark would you give them out of 10 and why?
  6. References: Please turn to their references. What is good and bad about it? What mark would you give them out of 3 and why?
  7. Typos: Was the report free of any noticeable typos? (Hint: There are at least five.) To what extent does their existence undermine the credibility of the report in your mind?
  8. Causality: So, are you convinced by their story? What do you think about the proposed change to superannuation? What mark would you give them out of 5 and why?

Introduction

In order to convince someone of your story papers and reports should be well-written, well-organized, and easy to follow. They should flow easily from one point to the next. They should have proper sentence structure, spelling, vocabulary, and grammar. Each point should be articulated clearly and completely without being overly verbose. Papers should demonstrate your understanding of the topics you are writing about and your confidence in discussing the terms, techniques and issues that are relevant. References must be included and properly cited because this enhances your credibility.

People who need to write: founders, VCs, lawyers, software engineers, designers, painters, data scientists, musicians, filmmakers, creative directors, physical trainers, teachers, writers. Learn to write.

Sahil Lavingia.

This is great advice. Writing well has done just as much for me as knowing how to code. I’d add that if you’re intimidated by writing, start a blog and write often about something you’re interested in. You’ll get better. At least that’s what I’ve done for the past 10 years. :)

Vicki Boykis.

This chapter is about how to write. By the end of it you will have a better idea of how to write short, detailed, quantitative papers that communicate exactly what you want them to and don’t waste the time of your reader.

Title, abstract, and introduction

A title is the first opportunity that you have to tell the reader your story. Ideally you will tell the reader exactly what you found. An effective title is critical in order to get your work read when there are other competing priorities. A title doesn’t have to be ‘cute’ to be great.

You should put your name and the date on the paper because this provides an important context to the paper.

For a six-page paper, a good abstract is a three to five sentence paragraph. For a longer paper your abstract can be slightly longer. The abstract should say: What you did, what you found, and why the reader should care. Each of these should just be a sentence or two, so keep it very high level.

You should then have an introduction that tells the reader everything they need to know. You are not writing a mystery story - tell the reader the most important points in the introduction. For a six-page paper, your introduction may be a paragraph or two. Three would likely be too much, but it depends on the context. Your introduction should set the scene and give the reader some background. For instance, you may like to start of a little broader, to provide some context to your paper. You should then describe how your paper fits into that context. Then give some high-level results - provide more detail than you provided in the abstract, but don’t get into the weeds - and finally broadly discuss next steps or glaring weaknesses. With regard to that high-level result: you need to pick one. If you have a bunch of interesting findings, then good for you, but pick one and write your introduction around that. If it’s compelling enough then the reader will end up reading all your other interesting findings in the discussion/results sections.

As an example: (TODO: this is just made up, update with something that is factual)

The Canadian Liberal Party has always struggled in rural ridings. In the past 100 years they have never won more than 25 per cent of them. But even by those standards the 2019 Federal Election was a disappointment with the Liberal Party winning only 2 of the 40 rural ridings. In this paper we look at why the performance of the Liberal Party in this most recent election was so poor. We construct a model in which whether the Liberal Party won the riding is explained by the number of farms in the riding, the average internet connectivity, and the median age. We find that as the median age of a riding increases, the likelihood that a riding was won by the Liberal Party decreases by 14 percentage points. Future work could expand the time horizon that is considered which would allow a more nuanced understanding of these effects.

The recommended readings provide some lovely examples of titles, abstracts, and introductions. Please take the time to briefly read these papers.

Figures, tables, equations, and technical terms

Figure and tables are a critical aspect of convincing people of your story. In a graph you can show your data and then let people decide for themselves. And in a table you can more easily summarise your data.

Figures, tables, equations, etc, should be numbered and then referenced in the text e.g. “Figure 1 shows…” and then have Figure 1.

You should make sure that all aspects of your graph are legible. Always label all of the axes. Your graphs should have titles, and the point that you want to communicate should be clear.

If you use a technical term, then it should be briefly explained in plain language for readers who might not be familiar with it. A great example of this is this post by Monica Alexander where she explains the Gini coefficient:

To look at the concentration of baby names, let’s calculate the Gini coefficient for each country, sex and year. The Gini coefficient measures dispersion or inequality among values of a frequency distribution. It can take any value between 0 and 1. In the case of income distributions, a Gini coefficient of 1 would mean one person has all the income. In this case, a Gini coefficient of 1 would mean that all babies have the same name. In contrast, a Gini coefficient of 0 would mean names are evenly distributed across all babies.

On brevity

'No more than four pages, or he's never going to read it. Two pages is preferable.'

Figure 1: ‘No more than four pages, or he’s never going to read it. Two pages is preferable.’

Source: Shipman, Tim, 2020, "The prime minister’s vanishing briefs’, The Sunday Times, 23 February, available at: https://www.thetimes.co.uk/article/the-prime-ministers-vanishing-briefs-67mt0bg95 via Sarah Nickson.

Insisting on two page briefs is sensible - not ‘government by ADHD’.

PM has to be across lots of issues - cannot and should not be across (most of) them in the same depth as secretaries of state. Danger lies in PM trying to take on too much and getting bogged down in detail.

This might irk officials who lack a sense of where their issue sits within the PM’s list of priorities - or the writing skills to draft a succinct brief.

But there’d be very few occasions when a brief to the PM warrants more than two pages.

This is not something peculiar to the current PM - other ministers have raised the same in interviews with @instituteforgov

Oliver Letwin complained of ‘huge amount of terrible guff, at huge, colossal, humungous length coming from some departments’ https://www.instituteforgovernment.org.uk/ministers-reflect/person/oliver-letwin/

Letwin sent briefs back and asked they be re-drafted to one quarter of the length.

‘Somewhere along the line the Civil Service had got used to splurge of the meaningless kind’

Similarly, Theresa Villiers talked about the civil service’s ‘frustrating tendency to produce six pages of obscure and rather impenetrable text’ and wishes she’d be firmer in sending documents back for re-drafting: https://www.instituteforgovernment.org.uk/ministers-reflect/person/theresa-villiers/

Sarah Nickson, 23 Feb 2020.

Brevity is important. Partly this because you are writing for the reader, not yourself, and your reader has other priorities. But it is also because as the writer it focuses you to consider what your most important points are, how you can best support them, and where your arguments are weakest.

If you don’t think that examples from government are persuasive, then please consider Amazon’s 2017 Letter to Shareholders, or other statements about Bezos and memo writing, for instance:

Well structured, narrative text is what we’re after rather than just text… The reason writing a 4 page memo is harder than “writing” a 20 page powerpoint is because the narrative structure of a good memo forces better thought and better understanding of what’s more important than what, and how things are related.

Jeff Bezos, 9 June 2004.

Other

Typos and other grammatical mistakes affect the credibility of your claims. If the reader can’t trust you to use a spell-checker then why should they trust you to use logistic regression? Microsoft Word has a fantastic spell-checker that is much better than what is available for R Markdown: copy/paste your work into there, look for the red lines and fix them in your R Markdown. Then look for the green lines and think about if you need to fix them in your R Markdown. If you don’t have Word then Google Docs is pretty good and so is Apple’s Pages.

A few other general tips that I have stolen from various people including the Reserve Bank of Australia’s style guide:

You should break these rules when you need to. But the only way to know whether you need to break a rule is to know the rules in the first instance.

Reporting regression results

This is such an important aspect that we will deal with it specifically.

TODO: ADD CONTENT

gtsummary

https://github.com/ddsjoberg/gtsummary

stargazer

modelsummary

https://github.com/vincentarelbundock/modelsummary

https://vincentarelbundock.github.io/modelsummary/