How to use this book

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

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

Things to DO are in ordered lists:

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

Things to know

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

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

1 + 1

[1] 2

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.

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:

1 + 1

[1] 2

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.

1mtcars |>
2  head()

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.

                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

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}
1 + 1
```

[1] 2

or

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

1 + 1
```

[1] 2

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

Notes, some important

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

Markdown was developed by JOHN GRUBER, as outlined on his Daring Fireball blog.

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

Important

You really should learn how to use Markdown as you will use it the whole semester, and hopefully for the rest of your life.

Or we may use a caution 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.

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.