write-like-mac

Distilled from 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: remove scaffolding, do not focus on process of arriving at conclusions. Remove scaffolidng particular do not have notes to coauthors except if commented; do not have text positioning statements relative to past drafts; e.g. no need for “not” clarificatory statements unless readers would have thought otherwise.

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

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. example: not: “The contribution is real, and it is not the contribution the introduction claims” rather: “The real contribution is different to what the introduction claims”

example: 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.

that

don’t skip ‘that’ if it creates ambiguity or makes things too terse:

Bad: The body still argues the result the abstract has already given up - Better: “The body still claims a result that the abstract has now dropped”-

Avoid effect-first constructions; esepcially with negation

Bad: The decline in Y was not the effect X was designed to produce. Better: X was not designed to produce a decline in Y

Passive voice

Avoid the passive voice. Agents first please.

Other 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:

• 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.

Appendix

Appendix should have its own table of contents Make sure that tables and figures are well placed in subsections and don’t bunch Order should largely track the order of the paper A PAP reconciliation section makes sense as a last item in an appendix: A PAP reconciliation section can usefully have two tables

1. a list of all the preregitered objects and a column saying where these are reported and a columns saying if the analysis has changed
2. a list of objects in the paper and an indication of where they were re-registered or are novel in cases in which anlaysis differs from planned, with good reason, report the planned analysis here if possible

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