Owning something that runs without you

The final difference between analysis and engineering is duration. An analysis is finished. A pipeline is never finished; it is owned, by someone, for years, and eventually by someone who has never met you.

Documentation that is worth writing#

Most data documentation is unread because it documents the wrong things. Nobody needs a description of what sum() does. The four things people actually need:

What is the grain? One sentence, at the top of every table. The single highest-value line of documentation in any warehouse.

Where does it come from, and what breaks if it is wrong? Upstream sources and downstream consumers. This is what the person debugging at 3am needs, and it is what lineage tooling gives you automatically if you let it.

What are the known quirks? "Orders before 2024-03 have no channel attribution because tracking launched then." "Revenue is gross of refunds; see fct_refunds." These save more time than everything else combined, because they cannot be inferred from the data and they will be rediscovered painfully by each new person.

Who owns it, and how urgent is it? A team, not a person. Plus the tier: does this wake someone up?

Everything else is optional. Four things, kept current, beat a wiki nobody updates.

Runbooks: written before the incident#

A runbook is what someone who is not you reads at 3am. Write it when the thing is built, while you still remember why.

# Runbook: orders ingestion

**What it does.** Pulls orders from the vendor API hourly into `raw.orders`,
then dbt builds `fct_order_lines`. SLA: complete for the previous day by 08:00.

**Owner.** #data-platform. Escalation: @on-call-data.

**Common failures**

1. *Vendor API 503.* Transient; retries handle it. If failing >2 hours, the
   vendor status page is at <url>. Safe to leave until morning — the
   lookback window will pick up missed rows automatically.
2. *Schema validation failure.* The vendor changed a field. Do NOT bypass the
   check. Look at the diff in the failure message, open a ticket with the
   vendor, and patch `models/staging/stg_orders.sql`. Data will backfill.
3. *Duplicate key test failure.* Almost always a double delivery. Safe to
   rerun the affected day — the model is idempotent.

**How to rerun one day**
    dbt run --select fct_order_lines --vars '{"run_date": "2026-03-14"}'

**How to backfill a range**
    scripts/backfill.sh 2026-03-01 2026-03-14   # bounded to 4 concurrent

**What NOT to do.** Do not truncate `raw.orders`. It is the only copy;
the vendor's API only serves 90 days.

That last section is the one people forget and the one that prevents disasters.

Handover#

When you leave a project — or a job — the handover is: someone else runs it for two weeks while you watch. Not a document. Not a meeting. They do it, you are available, and the gaps surface while you are still there to fill them.

Everything else is a substitute for this and works considerably less well.

Turning things off#

Every pipeline you build is a permanent maintenance obligation. The most underrated engineering skill is deleting things.

Audit annually:

• Which dashboards have not been opened in 90 days? Most BI tools report this.
• Which tables have no downstream reads?
• Which alerts have fired and been dismissed every time?
• Which models produce scores nobody consumes?

Then actually delete them. Announce a deprecation window, rename the object to deprecated_x for two weeks so anything depending on it breaks visibly and recoverably, then drop it.

On-call, and what you owe the person carrying it#

If your team is on-call, you owe the rotation:

• Runbooks for everything that pages. No exceptions. If it can page and has no runbook, either write one or downgrade it to a ticket.
• Alerts that mean something. Every page should be actionable. A page nobody can act on is a page that should not exist.
• Fixing the recurring ones. If the same alert fires weekly, it is not an incident any more — it is a design flaw with a snooze button.
• Reviewing pages regularly. A short monthly look at what fired, what was actionable, and what got dismissed. It is the only mechanism that stops alert volume growing forever.

The last thing#

Ten modules in, the through-line: your job is to make an organisation's decisions less wrong, and everything technical is in service of that.

The pipeline exists so the table is trustworthy. The table exists so the analysis is correct. The analysis exists so a decision improves. The monitoring exists so the whole chain stays true after you have stopped paying attention.

When you are choosing between two technical options, that chain is the tiebreaker. Not which is more interesting — which better serves the decision at the end of it.

Go build something. Everything on this site is free, and the datasets are waiting.