Why Every ML Engineer Should Practice Explaining Their Notebook Aloud

# [markdown] Churn prediction: summary
# Goal: probability a subscriber cancels within 30 days
# Data: 12 months of usage and billing, one row per customer
# Result: recall on churners beats baseline on a time split
# Read sections 3 and 5 first if short on time

# [markdown] 1. Setup
# [markdown] 2. Load data and check it
# [markdown] 3. Key decision: time-based split
# [markdown] 4. Features (with reasons)
# [markdown] 5. Baseline vs final model
# [markdown] 6. Error analysis by segment
# [markdown] 7. Limits and next steps
# [markdown] Appendix: experiments that did not work

"Let me start at the top, where I summarised the whole
project in four lines.

The goal was to predict which subscribers cancel in the next
30 days. The main decision was using a time-based split.
The final model beat a logistic regression baseline on recall.

I'll show you the data checks quickly, then the split
decision, then results. The appendix has failed experiments
if you want to see those. Where would you like to start?"

# Run the notebook from a clean kernel, save executed copy
jupyter nbconvert --to notebook --execute notebooks/churn.ipynb \
  --output churn_executed.ipynb

# Fail loudly if any cell takes too long (seconds)
jupyter nbconvert --to notebook --execute notebooks/churn.ipynb \
  --ExecutePreprocessor.timeout=600 --output churn_executed.ipynb

# Strip outputs before committing, to keep diffs readable
jupyter nbconvert --clear-output --inplace notebooks/churn.ipynb

# Optional: export a read-only HTML copy to share
jupyter nbconvert --to html notebooks/churn_executed.ipynb

import pandas as pd

df = pd.read_csv("data/customers.csv", parse_dates=["signup_date"])

# The notebook checks its own assumptions as it runs
assert df["customer_id"].is_unique, "duplicate customers"
assert df["churned"].isin([0, 1]).all(), "label must be 0/1"
assert df["monthly_fee"].ge(0).all(), "negative fees found"
assert df["signup_date"].max() <= pd.Timestamp("2026-01-01"), \
    "rows after the snapshot date"

print(df.shape)
print(df.isna().mean().sort_values(ascending=False).head(5))

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("data/customers.csv", parse_dates=["signup_date"])
rate = (df.assign(cohort=df["signup_date"].dt.to_period("M"))
          .groupby("cohort")["churned"].mean())

ax = rate.plot(marker="o", figsize=(8, 3))
ax.set_title("Churn rate by signup month")
ax.set_ylabel("share churned")
plt.tight_layout()
plt.show()

# [markdown cell under the chart]
# **What this showed:** newer cohorts churn more than older ones.
# **So I:** used a time-based split and added a cohort feature,
# because a random split would mix old and new behaviour.

"This chart is the reason for my biggest decision.

Churn is clearly higher for customers who signed up more
recently. If I had split randomly, the model would train and
test on a mix of old and new behaviour, and the score would
look better than it would on next month's customers.

So I split by time: train on earlier signups, validate on the
latest. The score went down a bit, but it is the honest one.
The note under the chart says exactly that, so anyone reading
the notebook gets the same story."

[ ] First cell is a markdown summary (goal, data, result)
[ ] One markdown header per section, numbered
[ ] Restart kernel + run all completed without errors
[ ] Execution counts are in order top to bottom
[ ] No absolute paths like C:/Users/... in any cell
[ ] Assert cells check shape, labels and key ranges
[ ] Every chart has a 'what it showed / so I' note
[ ] Failed experiments moved to an appendix
[ ] Large raw outputs cleared or collapsed
[ ] Final results table shows baseline vs model

0:00  Summary cell: goal, data, result, map of sections
1:00  Data checks: shape, asserts, one data issue found
2:30  Key decision cell (e.g. split) with its chart
4:30  Features: two or three with reasons
6:00  Baseline vs final table
7:30  Error analysis: weakest segment
8:30  Limits and next steps
9:00  Pause: 'Which part would you like to see in detail?'

Practise with a timer, sharing your screen to a friend.

Common questions while your notebook is shared:

- Can you rerun this cell?
- Where did you split the data?
- Why is this chart here?
- Where is the scaler fitted?
- What happens if this column has a new category?
- Which cell produces the number in your README?
- What did you try that is not in the main flow?

For each, know which cell to scroll to.