how-to-use.qmd

# How to use this book {.unnumbered}

We hold the deep belief that "all ships rise with the tide" when members of the data journalism community learn together, and this book seeks to add to that mission. We've written this textbook in the *first-person plural* to foster a sense of collaboration and shared learning between the reader and the authors. By using pronouns like “we” and “our,” our guide invites students into a learning journey that feels supportive and inclusive, rather than distant or instructional. It reflects the idea that learning to code is not a solitary task, but a process that many people engage in together. Our aim for this guide is to help beginners feel less intimidated, encouraging them to see mistakes and discoveries as part of a shared experience, not personal failures.

## Conventions and styles in this book {.unnumbered}

We will try to be consistent in the way we write documentation and lessons, but we are human and sometimes we break our own rules. In general, keep the following in mind:

### Things to do {.unnumbered}

Things to DO are in ordered lists:

1.  Do this thing.
2.  Then do this thing.

### Things to know {.unnumbered}

Things that need EXPLANATIONS are usually in text, like this very paragraph.

Sometimes details will be explained in lists:

-   This is the first thing I want you to know.
-   This is the second. You don't have to DO these things, just know about them.

### Code blocks {.unnumbered}

This book often runs the code that is shown, so you'll see the code and the result of that code below it.

```{r}
1 + 1
```

#### Copying code blocks

When you see code in the instructions, you can roll your cursor over the right-corner and **click on the copy icon** to copy the code clock content to your clipboard.

![](images/index-copy-clipboard.png)

You can then paste the code inside your coding program chunk.

That said, typing code yourself has many, many benefits. You learn better when you type yourself, make mistakes and have to fix them. **We encourage you to always type short code snippets.** Leave the copying to long ones.

#### Hidden code

Sometimes we want to include code in the book but not display it so you can try the to write the code yourself first. When we do this, it will look like this:

```{r}
#| code-fold: true
#| code-summary: "Click here to show the code"
1 + 1
```

If you click on the triangle or the words that follow, you'll reveal the code. Click again to hide it.

#### Annotated code

Sometimes when we are explaining code it is helpful to match lines of code to the explanation about them, which we do through annotated code.

```{r}
mtcars |> # <1>
  head() # <2>
```

1.  First we take the Motor Trend Car Road Tests data set AND THEN ...
2.  We pipe into the head() command, which gives us the "top" of the data.

When there are annotations like this you have to be careful if you are copying code from the book. Either copy it one line at a time or use the copy icon noted above.

#### Fenced code

Sometimes we need to show code chunk options that are added, like when explaining how to name chunks. In those cases, you may see the code chunk with all the tick marks, etc. like this:

```{r block-named}
#| echo: fenced
1 + 1
```

or

```{r}
#| echo: fenced
#| label: block-named-yaml

1 + 1

```

You can still copy/paste these blocks, but you'll get the entire code block, not just the contents.

### Notes, some important {.unnumbered}

We will use information callouts to set off a less important aside:

::: callout
Markdown was developed by JOHN GRUBER, as outlined on his [Daring Fireball blog](https://daringfireball.net/projects/markdown/).
:::

But sometimes those asides are important. We usually indicate that by using:

::: callout-important
You really should learn how to use [Markdown](https://rmarkdown.rstudio.com/) as you will use it the whole semester, and hopefully for the rest of your life.
:::

Or we may use a caution callout:

::: callout-caution
Not learning Markdown may result in you earning less than stellar grades.
:::

## macOS vs Windows

On some occasions we may need to give specific directions depending on your operating system or some other division. You would choose the tab that fits your situation.

::: {.panel-tabset}

### macOS

The authors use macOS so most directions are from that perspective.

### Windows

Usually you can use **Cntl + command** as a PC equivalent to **Cmd + command** on a Mac.

:::