# A Notebook That Tells a Story

A report notebook leads its reader from a title and the question to the short answer first, then the evidence, how it was done and what the data can't show, written in Markdown cells with headings, lists, bold and tables, and kept apart from the notebook you explored in.

Journeyman · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Arrange a report notebook in order, a title, the question, the short answer, the evidence, how it was done and what the data can't show
- Write Markdown cells with headings, lists, bold text and a table

## Key takeaways

- A notebook someone else reads follows an order, a title, the question, the short answer, the evidence, how it was done, and what the data can't show.
- The short answer comes first, so a busy reader gets it at once and reads on only for the proof.
- Each point of the short answer gets its evidence, a table or a chart from a code cell, with a sentence before it that says what to look at.
- In a Markdown cell,
- Explore in one notebook and tell the story in another, so the reader sees only the steps that lead to the answer.

You've found the answer. Now someone else has to follow it: a manager deciding next year's budget, a professor grading your project, a client who paid for the analysis. They didn't watch you work, and most of them won't read your code. This lesson turns a notebook into a report they can follow from the top.

The example is Pine Valley Community Center's classes, `classes.csv`: one row for each class session it ran from November 2025 to October 2026, 588 sessions in all. Its columns are `class_id`, `class_name`, `category` (fitness, arts, kids or technology), `month`, `capacity` (the seats), `signed_up`, `attended` and `fee`. Denise, the center's director, is planning next year's schedule. The data is our own made-up data.

## The notebook only you can read

An afternoon of exploring leaves a notebook like this one: `classes.head()`, `classes.shape`, three tries at a `groupby`, a cell that stopped with an error, a chart you didn't keep, and the answer Denise needs somewhere around cell 23. You know where to look. Denise opens it, sees code, scrolls, and closes it.

The quick fixes don't work either. Comments in the code help a programmer, not a director. A screenshot of cell 23 shows `86.5` with no hint of what it measures or which months it covers. An email with the numbers can't show where they came from, so nobody can check them.

![Two notebooks side by side. On the left, the exploring notebook: a long column of code cells with numbers out of order, one cell showing a red error, and the answer buried in the middle. On the right, the story notebook: a title, then the headings The question, The short answer, The evidence and What this data can't tell us, each with a few lines of text or one result under it](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/dfc402e6231b4b84ac54ef2a1de06166.webp)

## The shape of a story

A reader's questions come in an order: what was asked, what's the answer, how do you know, and can I trust it. A report notebook answers them in that order, each under its own heading:

1. **A title** that says what the report is about.
2. **The question**, in a sentence.
3. **The short answer**: the findings, with their numbers, in a few lines.
4. **The evidence**: a table or a chart for each point, from a code cell.
5. **How it was done**: the data, and the steps that matter, such as rows left out.
6. **What the data can't show**: the limits a reader should know before acting.

The short answer comes first, before any proof. Newspapers work this way, and at work it's called "bottom line up front": Denise may read only the first screen, so it has to hold the answer. In a business or statistics class you may see this part called an *executive summary*.

Under the evidence heading, a sentence says what to look at, then a code cell shows it:

```python
import pandas as pd

classes = pd.read_csv("classes.csv")
seats = classes.groupby("category")[["signed_up", "capacity"]].sum()
seats["fill_rate"] = (seats["signed_up"] / seats["capacity"] * 100).round(1)
seats.sort_values("fill_rate", ascending=False)
```

```text
            signed_up  capacity  fill_rate
category
technology        168       180       93.3
kids             1806      2088       86.5
fitness          4051      5400       75.0
arts             1276      1824       70.0
```

The `fill_rate` is the share of seats people signed up for, as a percent. Each number in the short answer points back to a cell like this, so anyone can check it.

## Markdown cells: headings, lists, bold and a table

The words of a report go in **Markdown** cells: plain text where a few marks set the formatting. Here is the short answer's cell, as you type it:

```markdown
## The short answer

- **Kids classes fill best:** 86.5% of their seats were taken.
- **January was the busiest month,** with more people at classes than any other month.
- **About 1 in 9 people who signed up didn't come** (11.6%).
```

- `#` (read "hash") at the start of a line makes the title. Use one, at the very top.
- `##` makes a section heading, one size smaller. Each part of the story gets one.
- `- ` (a dash and a space) starts a list item; `1. ` starts a numbered one.
- `**two stars**` on each side make the words bold, so the finding stands out from its details.

A small table uses pipes, `|` (read "pipe"), between the cells, and a line of dashes under the header row:

```markdown
| Category | Seats filled |
|---|---|
| kids | 86.5% |
| fitness | 75.0% |
```

Run the cell (**Shift+Enter**) and it shows as formatted text, with the table drawn as a grid. Type a table by hand only for a few numbers; numbers from the data belong in code cells, so they update when the data does.

## Explore in one notebook, tell the story in another

Exploring is real work, and its notebook is worth keeping: the dead ends show what you ruled out. Its textbook name is **exploratory data analysis**, or EDA. It isn't the report, though, so keep two notebooks in the project folder. `explore.ipynb` holds everything you tried. `story.ipynb` holds only the cells that lead to the answer, in order, with the Markdown that explains them. When the exploring finds something, copy the few cells that prove it into the story, then run the story with **Restart and Run All**, so every number in it comes from a clean run from the top.

## Check yourself

2 questions to try on the lesson page.

## So what

A notebook is finished when someone else can follow it: the answer first, then the evidence for each point, then what the data can't show, each under a heading a reader can find.

## Key terms

- [Markdown](https://www.ask-codey.com/glossary/markdown)
- [Notebook](https://www.ask-codey.com/glossary/notebook-python)
- [Exploratory Data Analysis](https://www.ask-codey.com/glossary/exploratory-data-analysis)

## Related

- [Tables People Can Read](https://www.ask-codey.com/lessons/data-tables-people-can-read)
- [What the Data Can and Can't Show](https://www.ask-codey.com/lessons/data-what-the-data-cant-show)
- [Sharing a Notebook as a Web Page](https://www.ask-codey.com/lessons/data-exporting-notebooks)

Source: https://www.ask-codey.com/lessons/data-notebook-that-tells-a-story
