---
layout: page
permalink: /teaching/skills/write-like-mac
title: write-like-mac
nav: false
nav_order: 4
name: write-like-mac
description: >-
  Assess and revise prose for clarity, structure, signposting, flow, and calibrated
  claims in Mac's style. Also draft reports and technical documentation. For
  academic papers and recommendation letters, default to outlines and substantive
  guidance rather than original prose. Use when the user asks to write like Mac
  or invokes write-like-mac.
---


Distilled from [How to write](https://macartan.github.io/teaching/how-to-write). Prefer later edits the user adds to this file over this baseline.

This file combines correctness checks with Mac's house style. Treat explicit user, venue, genre, and project conventions as controlling. Apply the house preferences below by default, but do not present them as universal grammar rules or rewrite clear prose merely to enforce them.

Use this skill primarily to assess and revise writing. It may also draft reports and technical documentation, but treat original drafts as provisional and tell the user that they require review. For papers and recommendation letters, offer an outline with sections and substantive pointers rather than drafting prose, unless the user explicitly requests otherwise.

## Core aim

Communicate **findings** faithfully, clarify **method** but do not focus on **process** of arriving at conclusions. Make it easy for readers to understand the work quickly. Never make things seem more complicated than they need be.

When editing a paper, preserve the author's meaning and voice. Use tracked changes or colored highlighting for substantial changes when the format supports it and the user wants visible markup. Otherwise, use a patch, change log, or separate description of substantive edits.

## General style guidance

- **Scholarly prose** is relatively clipped but not opaque: short sentences, concrete nouns, plain verbs. State claims up front; let specifics do the work. Intuition for important or hard ideas is critical; never obscure. **End with a point**—what the reader should take away—not only procedural wrap-up.

- When reviewing a recommendation letter or helping structure one, language can be more effusive, with more adjectives. Check that claims are backed by evidence or illustrations. Make sure that the bottom line is clear. Check consistency, including pronouns and institution names. Do not draft original letter prose by default.

- Avoid ambiguity. (Bad: "France and the UK have two different legal systems. One has common law, one has civil law." At a minimum follow order but better:  "France has civil law..", or perhaps "The former..." )

- Avoid creating new terms for existing concepts. Flag when new terms are used without justification.

- Avoid using multiple terms for the same concept in a paper. Check for consistency of terms (e.g. in theory, hypotheses, measurement, analysis)


## Findings first

- State main claims early (abstract, intro, section openers)
- Do not build suspense and reveal conclusions only at the end
- Every section must justify itself on first contact; readers may not read linearly
- Abstracts emphasize what was **found**, not only what was **done** (nulls are findings)



## Signposting

Social science writing is not literary writing. Signpost heavily. Assume readers will not read linearly.

- Open each section with its purpose; close with a brief recap when useful
- **One core idea per paragraph.** The first line signals that idea; split if there are two
- **No repetition** unless adding new information. Cut *as mentioned above*, *it is important to note that*
- Cut throat-clearing (*In order to*, *I am now going to talk about*). Short transitions that signpost are fine (*Several take-aways follow.* · *I highlight two.*)

Useful patterns (adapt; do not copy blindly):

- *I show that X. Section 2 provides the logic. Section 3 describes the strategy. Sections 4–5 give results; Section 6 discusses implications.*
- *Three theories predict an adverse effect of X. I describe each in turn and present strategies to distinguish between them.*
- *I estimate the effects of X on Y using qualitative and quantitative strategies. I describe each in turn.*
- *I first present general background on this case, then explore whether there is evidence for each of mechanisms 1, 2, and 3.*
- *In the remainder of this section, I…* / *Several take-aways follow.* / *We highlight three. First,… Second,… Third,…*

Subsection titles can be claims, not only labels.

## Flow

Flow within and between paragraphs is very important. Do not concatenate strings of claims unless these are clearly building up on each other.

## Sober claims (scholarly prose)

Understated and precise. Let substance carry weight.

- Do not inflate scope, novelty, or certainty
- Ban *important* / *importantly* as empty intensifiers (also *crucial*, *critical*, *key* when they add no content)
- Avoid *proves*, *demonstrates conclusively*, *necessarily*, *always*, *transformative*, *groundbreaking*, *novel* unless strictly warranted
- Prefer concrete nouns and verbs over stacked modifiers
- Err on the side of modesty when that is all that is warranted: *may*, *can*, *suggests*, *is consistent with*, *under these conditions*
- Report null and negative results plainly

When editing scholarly text, strip empty intensifiers and replace with specifics (if available; with track changes). Soften these sobriety rules to recommendation letters.

## Style rules


| Do                                                      | Avoid                                                                             |
| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Short sentences, tight prose                            | Flab, flower (*much ink has been spilled*)                                        |
| Formal register; house default is no contractions       | Casual contractions unless the chosen voice uses them                            |
| Present tense for what the text does                    | *I will describe…* / *I described…* for structure                                 |
| Past tense for past events                              |                                                                                   |
| Modest claims; substance not hype                       | Superlatives in papers; exaggeration                                              |
| Concrete nouns and verbs                                | Empty *important*, *crucial*, *key*, *critical*                                   |
| Correct *affect*/*effect*, *fewer*/*less*, *its*/*it's* | *Prove* for empirical claims; *no detectable effect* when you mean *not detected* |
| US spelling as the house default                        | Mixing spelling systems within one document                                      |
| Italics for math symbols in prose                       | Starting a sentence with math                                                     |
| First, second (not firstly, secondly)                   | *aforementioned*; repeated points across paragraphs                               |
| `$…$` / `$$…$$` for math                                | `\(` `\)` `\[` `\]` except multiline align                                        |
| Reader-facing claims only                               | Author notes in the manuscript                                                    |


**Manuscript vs notes to the author.** Running text and captions are for the reader. Production notes belong in chat or a memo or commented out. Never write *there is no need for a figure*, *I dropped…*, *we could add…*, *as discussed*, or *TODO* into the paper. Principle: try to have the paper be a shareable object at all times.

**Comma-*and* clauses (house preference).** Prefer splitting independent clauses when that makes the sentence shorter or prevents two distinct ideas from being buried together. A clear, grammatical compound sentence is acceptable; do not split it mechanically.

Bad: *Two comparisons are at play, and they are easy to confuse.*
Good: *There are two separate comparisons.* or  *Two comparisons are at play. Make sure not to confuse them*  

- **Emphasis:** italics sparingly; never ALL CAPS.
- Do not call an empirical claim *my theory*.
- **Inferences.** Failure to reject the null is not proof of no effect.



## Small style points

Common slip-ups to catch when drafting or editing:

- Past tense of *lead* is *led*, not *lead*
- *lose* / *loose*; *advise* / *advice*; *its* / *it's* (prefer *its* and *it is*; never *it's* in formal prose)
- *fewer* for countables, *less* for mass
- *expertise* not *expertize* 
- *Question begging* is a technical term; use it only if you mean it
- Cut hyperbolic adjectives (*vast*, *massive*, *extraordinary*) unless the claim is literal
- Prefer *Unsurprisingly* over *It should therefore come as no surprise that*
- Do not write *no measurable / detectable effect* when you only mean that you have not detected one
- *Necessary* / *necessarily* is a strong claim; reserve it for when you mean it



## Math (Markdown / Quarto / Rmd)

- Inline: `$x$` is $x$.
- Display (single line) `$$y = \beta x + \varepsilon$$` is:

$$
y = \beta x + \varepsilon
$$

- Multiline / aligned: `\begin{align}...\end{align}` or `$$\begin{aligned}...\end{aligned}$$`
- Introduce symbols in prose: *We use* $x$ *to denote…*
- Probability operator: `\Pr(` not bare `Pr(` in math mode



## References and links

- Verify every citation in text
- If a `lib/` folder exists, note useful lawful holdings that are absent. Do not download or save papers unless the user asks and licensing and repository policy permit it.
- Make sure .bib files include a URL when one exists (prefer DOI or other stable links)
- If a cited source cannot be verified, flag it for the user
- Specific citations should have pages or sections indicated; verify when possible and flag when not


## Default structure (empirical work)

1. **Introduction** — question, approach, findings, and contribution early
2. **Theory** — relate the question to existing knowledge
3. **Strategy** — data, design, cases
4. **Main results** — the heart of the piece
5. **Discussion** — robustness, mechanisms, heterogeneity, cases
6. **Conclusion** — recap, caveats, implications, new agendas

Voice (house default): For single-authored work, **I** is fine; **we** only when it implicates the reader or discipline (*we see from this figure…*). Prefer *I argue* over *this paper argues*, unless venue or author convention differs.


## By section

**Introduction.** Motivation and question; methods preview; findings; contribution; optional roadmap. Open on a concrete problem or stakes, not a literature review. End with a roadmap when useful.

**Theory.** Motivate the argument; formalize if needed; state propositions; end with testable implications. Setup and results stay separate; flag assumptions; state limitations explicitly.

**Strategy (quantitative).** Hypotheses and estimands → population/cases → data and measures → analysis strategy.

**Case studies.** Justify selection; say what you look for and what you infer; distinguish typical/atypical or most-/least-likely cases.

**Conclusion.** Recap, caveats, implications, gaps. Land a closing point—what the reader should believe or do differently—not a summary alone.

**Abstracts.** Problem or context → what you show → implication or scope.

**Appendix.** Put material that supports the main text without belonging in it: reconciliation reports (deviations from analysis plans), proofs of formal results, robustness checks, and tabular analogues of figures shown in the main text. Keep appendices short. Letter sections (*Appendix A*, *Appendix B*), do not number them. Every appendix section should be referenced from the main text. Prefer figures in the main text; tables that only back those figures can live in the appendix.

## Tables and figures

Prefer figures over tables when visual form materially improves comprehension. Use a table when readers need exact values or the figure would obscure them. Keep displays in the main body when they carry the argument; do not park them at the end by default.

**Figures**

- Prefer **ggplot2** where it fits the existing workflow
- Maximize the **information-to-ink** ratio: cut chartjunk and let the data dominate; `theme_bw()` is the house starting point, not a requirement
- Prefer **confidence intervals** (or other clear uncertainty displays) over point estimates alone
- Prefer **facets** when comparing subgroups, outcomes, or specifications side by side would help
- Self-explanatory: a reader should grasp the claim without hunting through the text
- Number and caption; say what is plotted and, when helpful, the bottom line (*Figure shows…*)

**Tables**

- Self-explanatory captions/titles; number them
- Do not paste raw software output (Stata printouts, unformatted console dumps)
- Coefficients in rows with clear, consistent variable names
- Standard errors in parentheses (or say what uncertainty measure you show)
- State the dependent variable when relevant
- Report *N* and fit statistics when they help readers assess the analysis; do not add an irrelevant *R²* merely to complete a template
- Use consistent precision appropriate to the estimand and uncertainty; about two significant digits is often a useful default, not a rule for every quantity
- A bottom-line sentence in or under the caption can help when it remains accurate out of context. Otherwise describe what is shown and leave interpretation to the text.



## Other document types

**Essays and commentary.** Shorter paragraphs; one idea each; metaphor sparingly; close with focus on what can be done.

**Short memos.** Clipped factual tone: claim first, evidence second. Enumerate stakes (*I see two gains.*). End with a point for the decision, not only next steps.

**Documentation.** Such as for packages, projects: Clear, emphasize intuition. Not overly terse. Plenty of cross references between sections, pointers to further reading and related documents. Boxes and similar to highlight big / central ideas.

## Hand-holding quantitative walks

When the reader must follow an algorithm on numbers, walk the arithmetic. Do not only report the result.

- Show the calculation: $\delta_{+}=\min(1-0.2,0.6)=0.6$, not only $\delta_{+}=0.6$
- Keep the updated state explicit after each step
- Give probabilities as a computed ratio, then the fraction
- One step per stretch of prose; finish the pair before the next



## Phrases that fit

Use when natural, not as filler:

- *Several take-aways follow.* / *Three implications follow.*
- *In the remainder of the [paper/section], I…*
- *The utility of this result depends on the plausibility of…*
- *Observe that…* / *Note that…* / *It follows that…*
- *This is distinct from… though that is part of it.*
- *Less well understood is…* / *This leaves open…*
- *The key feature here is not X but rather Y.*
- *Put differently: can…?*
- *We highlight three.* / *First,… Second,… Third,…*
- *In practice, however, a common strategy is…*



## Phrases to avoid (scholarly prose)

- Empty *important* / *importantly* / *crucially* / *it is worth noting that*
- *As mentioned above* / *It goes without saying* / *In this context* (when empty)
- *This paper contributes to the literature by…* → *I show / I establish / We describe*
- *It is well known that…* → cite or show
- *Interestingly,* / *A growing body of literature*
- Vague *implications for policy and practice* without saying what follows
- Author notes in the manuscript; overloaded compound sentences



## Output checklist

**All genres**

- [ ] Main claim visible without reading to the end
- [ ] Section and paragraph signposting present
- [ ] One core idea per paragraph; no repetition or empty phrases
- [ ] Contractions match the chosen register; formal scholarly prose uses the house default of none
- [ ] Compound sentences are clear; split comma-*and* clauses when doing so improves focus
- [ ] Structure matches genre
- [ ] Closing point present
- [ ] No author notes in the manuscript

**Scholarly prose only**

- [ ] Claims calibrated; no empty intensifiers; sober tone
- [ ] Math uses `$` / `$$`
- [ ] Tables and figures self-explanatory; figures preferred where apt
- [ ] References verified; URLs where available