Markdown and
universal writing1 / 23

Writing up research is a
complicated, messy process!

2 / 23

Itty bitty pieces3 / 23

Itty bitty pieces

Data Statistical results

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

Citations

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

Citations

Your actual words

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

Citations

Your actual words

Each of these comes from a different place!

3 / 23

Spending a full day of writing in the mountains or the beach with a notebook sounds cool, but it's really infeasible with any sort of academic writing - too much going on!

Two general approaches for this mess4 / 23

Two general approaches for this mess

The Office model

Put everything in one document

4 / 23

Two general approaches for this mess

The Office model

Put everything in one document

The Engineering model

Embrace the bittiness and compile it all at the end

4 / 23

https://plain-text.co/index.html#introduction

The Office model

Everything lives in
one .docx file

Drag images in

Copy/paste stats from R or Stata

Connect Word to Zotero or Endnote

Track versions with filenames: ms.docx, ms2_final.docx, ms2_final_final.docx

Final output = .docx file

5 / 23

The Engineering model

Everything lives separately and is combined in the end

Type text in a plain text document

Import images automatically

Import stats automatically from
R scripts (.R or .Rmd) or .do files

Store citations in reference manager

Track versions with git

Final output = whatever you want (Word, PDF, HTML)

6 / 23

No one right way!7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

The whole world runs on Word

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

The whole world runs on Word

Even if you're a strict Engineering person,
you'll still collaborate with Office people!

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

The whole world runs on Word

Even if you're a strict Engineering person,
you'll still collaborate with Office people!

Coauthors will work in Word, advisers will give comments
and track changes in Word, journals will demand final Word files

7 / 23

Reproducibility8 / 23

Reproducibility

The Engineering model is definitely more fiddly

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

No need to copy/paste new results,
add updated figures, reformat citation, etc.

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

No need to copy/paste new results,
add updated figures, reformat citation, etc.

There's a record of everything you do!

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

No need to copy/paste new results,
add updated figures, reformat citation, etc.

There's a record of everything you do!

Your findings are reproducible by anyone (and yourself!)

8 / 23

Austerity and Excel

Debt:GDP ratio
90%+ → −0.1% growth

9 / 23

Austerity and Excel

Debt:GDP ratio
90%+ → −0.1% growth

The Path to Prosperity 2013 house budget — Paul Ryan's 2013 House budget resolution

9 / 23

2013 House Budget Resolution

Austerity and Excel

10 / 23

Austerity and Excel

Paul Krugman on Excel and reproducibility — From Paul Krugman, "The Excel Depression"

10 / 23

Paul Krugman on the reproducibility crisis

Austerity and Excel

11 / 23

Austerity and Excel

Debt:GDP ratio = 90%+ → 2.2% growth (!!)

11 / 23

Genes and Excel

Septin 2

Membrane-Associated Ring Finger (C3HC4) 1

2310009E13

12 / 23

Genes and Excel

Septin 2

Membrane-Associated Ring Finger (C3HC4) 1

2310009E13

12 / 23

Genes and Excel

Septin 2

Membrane-Associated Ring Finger (C3HC4) 1

2310009E13

20% of genetics papers between 2005–2015 (!!!)

12 / 23

General guidelines

Don't touch the raw data

If you do, explain what you did!

13 / 23

General guidelines

Don't touch the raw data

If you do, explain what you did!

Use self-documenting, reproducible code

The whole point of this Engineering model! (R Markdown!)

13 / 23

General guidelines

Don't touch the raw data

If you do, explain what you did!

Use self-documenting, reproducible code

The whole point of this Engineering model! (R Markdown!)

Use open formats

Use .csv, not .xlsx

13 / 23

Engineering model in real life

Airbnb's data science tools — Airbnb, ggplot, and rmarkdown

14 / 23

Engineering model in real life

UK Statistics pipeline, short — The UK's reproducible analysis pipeline

14 / 23

https://peerj.com/preprints/3182.pdf + https://gdsdata.blog.gov.uk/2017/03/27/reproducible-analytical-pipeline/

Overview of the process

15 / 23

https://plain-text.co/pull-it-together.html#pull-it-together

Can get more complicated!

16 / 23

https://plain-text.co/pull-it-together.html#pull-it-together

Universal writing

$\LaTeX$

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

Run latexmk from the terminal or click the "compile" button in your TeX editor and you'll stitch together all your separate writing, tables, images, and citations

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

Run latexmk from the terminal or click the "compile" button in your TeX editor and you'll stitch together all your separate writing, tables, images, and citations

HOWEVER, the world runs on .docx

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

Run latexmk from the terminal or click the "compile" button in your TeX editor and you'll stitch together all your separate writing, tables, images, and citations

HOWEVER, the world runs on .docx

There are ways to convert from .tex to .docx, but they're a pain

17 / 23

Three syntaxes

If you want to be able to write in LaTeX, but also have HTML for a blog post later, and also have a Word file for a journal later, you have to learn (and write with!) all these!

18 / 23

Three syntaxes

If you want to be able to write in LaTeX, but also have HTML for a blog post later, and also have a Word file for a journal later, you have to learn (and write with!) all these!

Format	LaTeX	HTML	Word
Bold	\textbf{Something}	<b>Something</b>	Click on stuff
Heading 2	\subsection{Something}	<h2>Something</h2>	Click on stuff
Link	\href{google.com}{Link}	<a href="google.com">Link</a>	Click on stuff
Citation	\cite{Heiss2020}	lolz	lolz
Math	y = \beta_0 + \beta_1 x_1	lolz	Equation editor

18 / 23

Markdown + pandoc

Solution: Use a universal syntax

19 / 23

Markdown + pandoc

Solution: Use a universal syntax

Write with one simplified syntax and
convert from that to whatever output you want.

19 / 23

Markdown + pandoc

Solution: Use a universal syntax

Write with one simplified syntax and
convert from that to whatever output you want.

Format	Markdown
Bold	Something
Heading 2	## Something
Link text	[Link](google.com)
Citation	@Heiss2020
Math	y = \beta_0 + \beta_1 x_1

19 / 23

Markdown + pandoc

Solution: Use a universal syntax

Write with one simplified syntax and
convert from that to whatever output you want.

Format	Markdown
Bold	Something
Heading 2	## Something
Link text	[Link](google.com)
Citation	@Heiss2020
Math	y = \beta_0 + \beta_1 x_1

19 / 23

pandoc

The magic glue that makes this all work

20 / 23

pandoc

The magic glue that makes this all work

# To HTML
pandoc manuscript.md -o manuscript.html
# To Word
pandoc manuscript.md -o manuscript.docx
# To PDF (through LaTeX)
pandoc manuscript.md -o manuscript.pdf

20 / 23

Overview again

21 / 23

The Universal Markdown-based model22 / 23

The Universal Markdown-based model

Text editor

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

pandoc

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

pandoc

(Not in this class: Automation with Makefiles)

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

pandoc

(Not in this class: Automation with Makefiles)

(Not in this class: Version control with git/GitHub)

22 / 23

Let's play with
Markdown and pandoc!

23 / 23

Markdown and
universal writing1 / 23

Writing up research is a
complicated, messy process!

2 / 23

Itty bitty pieces3 / 23

Itty bitty pieces

Data Statistical results

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

Citations

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

Citations

Your actual words

3 / 23

Itty bitty pieces

Data Statistical results

Fieldwork Interviews Analysis

Figures Images Tables

Citations

Your actual words

Each of these comes from a different place!

3 / 23

Spending a full day of writing in the mountains or the beach with a notebook sounds cool, but it's really infeasible with any sort of academic writing - too much going on!

Two general approaches for this mess4 / 23

Two general approaches for this mess

The Office model

Put everything in one document

4 / 23

Two general approaches for this mess

The Office model

Put everything in one document

The Engineering model

Embrace the bittiness and compile it all at the end

4 / 23

https://plain-text.co/index.html#introduction

The Office model

Everything lives in
one .docx file

Drag images in

Copy/paste stats from R or Stata

Connect Word to Zotero or Endnote

Track versions with filenames: ms.docx, ms2_final.docx, ms2_final_final.docx

Final output = .docx file

5 / 23

The Engineering model

Everything lives separately and is combined in the end

Type text in a plain text document

Import images automatically

Import stats automatically from
R scripts (.R or .Rmd) or .do files

Store citations in reference manager

Track versions with git

Final output = whatever you want (Word, PDF, HTML)

6 / 23

No one right way!7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

The whole world runs on Word

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

The whole world runs on Word

Even if you're a strict Engineering person,
you'll still collaborate with Office people!

7 / 23

No one right way!

The Office model can be clunky and you'll
inevitably forget to update figures, tables, results, etc.

BUT

The whole world runs on Word

Even if you're a strict Engineering person,
you'll still collaborate with Office people!

Coauthors will work in Word, advisers will give comments
and track changes in Word, journals will demand final Word files

7 / 23

Reproducibility8 / 23

Reproducibility

The Engineering model is definitely more fiddly

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

No need to copy/paste new results,
add updated figures, reformat citation, etc.

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

No need to copy/paste new results,
add updated figures, reformat citation, etc.

There's a record of everything you do!

8 / 23

Reproducibility

The Engineering model is definitely more fiddly

BUT

There's less cognitive load!

No need to copy/paste new results,
add updated figures, reformat citation, etc.

There's a record of everything you do!

Your findings are reproducible by anyone (and yourself!)

8 / 23

Austerity and Excel

Debt:GDP ratio
90%+ → −0.1% growth

9 / 23

Austerity and Excel

Debt:GDP ratio
90%+ → −0.1% growth

9 / 23

2013 House Budget Resolution

Austerity and Excel

10 / 23

Austerity and Excel

10 / 23

Paul Krugman on the reproducibility crisis

Austerity and Excel

11 / 23

Austerity and Excel

Debt:GDP ratio = 90%+ → 2.2% growth (!!)

11 / 23

Genes and Excel

Septin 2

Membrane-Associated Ring Finger (C3HC4) 1

2310009E13

12 / 23

Genes and Excel

Septin 2

Membrane-Associated Ring Finger (C3HC4) 1

2310009E13

12 / 23

Genes and Excel

Septin 2

Membrane-Associated Ring Finger (C3HC4) 1

2310009E13

20% of genetics papers between 2005–2015 (!!!)

12 / 23

General guidelines

Don't touch the raw data

If you do, explain what you did!

13 / 23

General guidelines

Don't touch the raw data

If you do, explain what you did!

Use self-documenting, reproducible code

The whole point of this Engineering model! (R Markdown!)

13 / 23

General guidelines

Don't touch the raw data

If you do, explain what you did!

Use self-documenting, reproducible code

The whole point of this Engineering model! (R Markdown!)

Use open formats

Use .csv, not .xlsx

13 / 23

Engineering model in real life

14 / 23

Engineering model in real life

14 / 23

https://peerj.com/preprints/3182.pdf + https://gdsdata.blog.gov.uk/2017/03/27/reproducible-analytical-pipeline/

Overview of the process

15 / 23

https://plain-text.co/pull-it-together.html#pull-it-together

Can get more complicated!

16 / 23

https://plain-text.co/pull-it-together.html#pull-it-together

Universal writing

$\LaTeX$

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

Run latexmk from the terminal or click the "compile" button in your TeX editor and you'll stitch together all your separate writing, tables, images, and citations

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

Run latexmk from the terminal or click the "compile" button in your TeX editor and you'll stitch together all your separate writing, tables, images, and citations

HOWEVER, the world runs on .docx

17 / 23

Universal writing

$\LaTeX$

You might know LaTeX—it's a scientific typesetting language

Great! It's a way to do the Engineering model

Run latexmk from the terminal or click the "compile" button in your TeX editor and you'll stitch together all your separate writing, tables, images, and citations

HOWEVER, the world runs on .docx

There are ways to convert from .tex to .docx, but they're a pain

17 / 23

Three syntaxes

If you want to be able to write in LaTeX, but also have HTML for a blog post later, and also have a Word file for a journal later, you have to learn (and write with!) all these!

18 / 23

Three syntaxes

If you want to be able to write in LaTeX, but also have HTML for a blog post later, and also have a Word file for a journal later, you have to learn (and write with!) all these!

Format	LaTeX	HTML	Word
Bold	\textbf{Something}	<b>Something</b>	Click on stuff
Heading 2	\subsection{Something}	<h2>Something</h2>	Click on stuff
Link	\href{google.com}{Link}	<a href="google.com">Link</a>	Click on stuff
Citation	\cite{Heiss2020}	lolz	lolz
Math	y = \beta_0 + \beta_1 x_1	lolz	Equation editor

18 / 23

Markdown + pandoc

Solution: Use a universal syntax

19 / 23

Markdown + pandoc

Solution: Use a universal syntax

Write with one simplified syntax and
convert from that to whatever output you want.

19 / 23

Markdown + pandoc

Solution: Use a universal syntax

Write with one simplified syntax and
convert from that to whatever output you want.

Format	Markdown
Bold	Something
Heading 2	## Something
Link text	[Link](google.com)
Citation	@Heiss2020
Math	y = \beta_0 + \beta_1 x_1

19 / 23

Markdown + pandoc

Solution: Use a universal syntax

Write with one simplified syntax and
convert from that to whatever output you want.

Format	Markdown
Bold	Something
Heading 2	## Something
Link text	[Link](google.com)
Citation	@Heiss2020
Math	y = \beta_0 + \beta_1 x_1

19 / 23

pandoc

The magic glue that makes this all work

20 / 23

pandoc

The magic glue that makes this all work

# To HTML
pandoc manuscript.md -o manuscript.html
# To Word
pandoc manuscript.md -o manuscript.docx
# To PDF (through LaTeX)
pandoc manuscript.md -o manuscript.pdf

20 / 23

Overview again

21 / 23

The Universal Markdown-based model22 / 23

The Universal Markdown-based model

Text editor

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

pandoc

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

pandoc

(Not in this class: Automation with Makefiles)

22 / 23

The Universal Markdown-based model

Text editor

(R) Markdown

pandoc

(Not in this class: Automation with Makefiles)

(Not in this class: Version control with git/GitHub)

22 / 23

Let's play with
Markdown and pandoc!

23 / 23

↑, ←, Pg Up, k	Go to previous slide
↓, →, Pg Dn, Space, j	Go to next slide
Home	Go to first slide
End	Go to last slide
Number + Return	Go to specific slide
b / m / f	Toggle blackout / mirrored / fullscreen mode
c	Clone slideshow
p	Toggle presenter mode
t	Restart the presentation timer
?, h	Toggle this help
o	Tile View: Overview of Slides

Markdown anduniversal writing

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Two general approaches for this mess

Two general approaches for this mess

Two general approaches for this mess

The Office model

The Engineering model

No one right way!

No one right way!

No one right way!

No one right way!

No one right way!

No one right way!

Reproducibility

Reproducibility

Reproducibility

Reproducibility

Reproducibility

Reproducibility

Reproducibility

Austerity and Excel

Austerity and Excel

Austerity and Excel

Austerity and Excel

Austerity and Excel

Austerity and Excel

Genes and Excel

Genes and Excel

Genes and Excel

General guidelines

General guidelines

General guidelines

Engineering model in real life

Engineering model in real life

Overview of the process

Can get more complicated!

Universal writing

Universal writing

Universal writing

Universal writing

Universal writing

Universal writing

Three syntaxes

Three syntaxes

Markdown + pandoc

Markdown + pandoc

Markdown + pandoc

Markdown + pandoc

pandoc

pandoc

Overview again

The Universal Markdown-based model

The Universal Markdown-based model

The Universal Markdown-based model

The Universal Markdown-based model

The Universal Markdown-based model

The Universal Markdown-based model

Help

Markdown and universal writing

Markdown anduniversal writing

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Itty bitty pieces

Two general approaches for this mess

Two general approaches for this mess

Two general approaches for this mess

The Office model

The Engineering model

No one right way!

No one right way!

Markdown and
universal writing

Markdown and
universal writing