Writing style guide - ganong-noel/lab_manual GitHub Wiki

For style questions not explicitly addressed here, we will follow whatever the AER does.

Our internal conventions

  • Capitalize “Section”
  • “U.S.” has two periods
  • Refer to Appendix sections as “Appendix <letter.number>”.
  • A paper is singular (e.g. “Ganong and Noel finds”). Strive to describe a paper, its data and its research design, rather than the author(s).
  • Wrap equation numbers in parentheses: “Equation (1), not equation 1.”
  • All Lyx comments (“yellow stickies”) should begin with “SOURCE” or “BACKGROUND”
  • Percent not %

References

  • In general, we want to reference online appendices by their order in the appendix. Sometimes, however, we deviate because we need to maintain the overall structure of the appendices.
  • AER guide: “On first references, use the full name followed by the abbreviation in parentheses. Subsequent references should use abbreviation only; for example: Social Science Research Council (SSRC) [first reference], SSRC [subsequently].”
    • Exception: If an acronym is not well-known to readers and hasn’t been used in several sections it is OK to re-spell it out.
  • Minimize the use of footnotes in an appendix
  • Citation guidance
    • Use “et al.” for references to papers with four or more authors: “Gentzkow et al. 2004” not “Gentzkow, Glaeser, Goldfish, and Goldin 2004.”
    • Separate multiple references in parenthetical references with semicolons not commas: “(Gentzkow and Shapiro 2006; Shapiro 2012)” not “(Gentzkow and Shapiro 2006, Shapiro 2012)”. However, a list of references outside of parentheses should be separated by commas.
    • When there is a list of citations, the papers should be ordered alphabetically by the last name of the first author

From Gentzkow Shapiro Lab

  • Except where noted below, we use a "conversational" rule to decide where to put commas. There is no need to flag commas to be added or subtracted unless there is a clear typo or a significant issue of clarity or ambiguity.
  • References to numbered tables, figures, sections, and appendixes should be capitalized: “See Table 3” not “See table 3.”
  • References to numbered equations should be lowercase: "See equation (3)" not "See Equation (3)".
  • Use “serial comma”: “apples, pears, and bananas” not “apples, pears and bananas.”
  • No commas before years in parenthetical references: “(Gentzkow and Shapiro 2006)” not “(Gentzkow and Shapiro, 2006).”
  • No nested parentheses in parenthetical references: "Some authors (e.g., Gentzkow and Shapiro 2010)..." not "Some authors (e.g., Gentzkow and Shapiro (2010))..."
  • Possessive apostrophe before parenthetical reference: "Gentzkow's (2006) approach" not "Gentzkow (2006)'s approach"
  • Use numerals for numbers >=10 (“increases 10 percentage points”) and write out numbers <10 (“increases nine percentage points”). This rule should be broken when necessary to maintain parallelism (“with 3, 12, and 100 observations respectively” not “with three, 12, and 100 observations respectively”).
  • The “references” section of the online appendix should include only those references cited in the online appendix but not cited in the body of the paper.

capitalization

  • Titles of sections and subsections, tables, figures, subfloats within tables and figures are written in “title caps” (e.g., "Main Results" not "Main results").
  • Axis labels, row and column headers in tables, etc. should only have the first word capitalized (e.g., “Log population” not “Log Population”)

From Econscribe (aka Varanya Chaubey)

Not hard and fast rules, but excessive violations should be flagged

  • Sentences per Paragraph:
    • Target is 5 or 6 sentences. No more than 8. We are more willing to allow much shorter paragraphs of 2 or 3 sentences.
    • “Typically, most RAP-relevant paragraphs have about 5 or 6 sentences. If there are many more, there is either more than one point tried in the paragraph or a point that is not clear enough to distill the details. If there are fewer than six sentences, the idea may need further development to stand on its own”
  • Words per sentence
    • “20 to 25 tops”

slides

  • No acronyms
  • Author names: write out <= 2 names. For > 2, use et al.
  • Have a button at the end of each section to allow you to jump to the conclusion slide