How I Structure Ops Scripts So the Next Person Can Run Them

Published 2026-04-13 by Faraz Rahimi

A script that only runs in your venv is a liability. Treat internal automation like a tiny product with a README that a lead can follow.

Tags: Python, Documentation, Operations, Maintainability, unlisted

I put a purpose sentence at the top, the exact command, the inputs, the outputs, and whether it is safe to rerun. If that does not fit in twenty lines, the script is doing too much.

Config lives in a file or env, not in a comment that says TODO change this path. Secrets do not live in the repo. I have seen API keys in macros. Once is enough.

One job per entry point

ingest_vendor.py does not also send Slack and rebuild the dashboard. Compose those. When ingest breaks, you should not wonder if Slack is why.

A dry run flag is documentation

--dry-run that prints counts is how someone new gains courage. Without it, they will wait for you to come back from lunch.

Original post: https://farazrahimi.com/posts/how-i-structure-ops-scripts-so-the-next-person-can-run-them