Documentation & Literate Programming

Session 9

README

README.md is the landing page for your GitHub repo, and the first place to look for help understanding it.

Brief project summary
Project status (just an experiment, WIP, archived?)
How to give credit (e.g. if it is associated with a published paper)
Structure of repo (which files do what?)
Instructions on how to reproduce results

Example READMEs for research compendia

Markdown

Markdown is a “markup language” that let’s you write plain text to indicate formatting. For example:

**bold text** becomes bold text
~~strikethrough~~ becomes ~~strikethrough~~
$E = mc^2$ becomes $E = mc^2$
[link](https://www.google.com) becomes link
`code()` becomes code()

Check Help > Markdown quick reference in RStudio

README.md

Exercise (~5 min)

Edit a README.md using some of the markdown tips from the RStudio markdown quick reference

Common markdown pitfalls

Spaces between elements matter! How would you fix each of these?

###Heading 3

###Heading 3

Colors:
- red
- green

Colors: - red - green

1.Number one
2.Number two

1.Number one 2.Number two

Common markdown pitfalls

Spaces within elements don’t matter!

This     sentence still  gets    rendered  correctly!

This sentence still gets rendered correctly!

Single line breaks don't separate paragraphs.
See?

You need two line breaks for that!

Single line breaks don’t separate paragraphs. See?

You need two line breaks for that!

Quarto

What is Quarto?

“An open-source scientific and technical publishing system”

Mix markdown, code, and the output of code
Produce beautifully formatted documents in a variety of formats (html, Word, pdf, etc.)
Data analysis notebook
Presentations for collaborators
Reproducible manuscripts
…and more!

How does Quarto work?

Command line tool, not an R package, but works well with RStudio

Anatomy of a .Qmd file

myreport.qmd

---
title: "My Report"
author: "Eric Scott"
format: 
  html:
    toc: true
---

```{r}
#| label: load-packages
#| include: false

library(tidyverse)
library(gapminder)
```

## Data

My data source is the [gapminder](https://www.gapminder.org/) dataset.

```{r}
head(gapminder)
```

Our turn

Create a new Quarto Document
Practice editing and rendering
Explore the Visual editor mode
Add citations and cross-references

Learn more

Getting started tutorial
Quarto for Academics talk
Full Quarto guide and reference (searchable!)
Quarto Manuscripts (upcoming feature)

Drop-in Session & Showcase

This Thursday (10/5): Getting Credit For Your Work
Next week (10/10, 10/12): No workshops!
Tuesday 10/17: Drop-in help session
Tuesday 10/24: Reproducibility show & tell