Why I Document Scripts Like They're Products

Published 2025-08-31 by Faraz Rahimi

A script with a user, a failure mode, and a rerun story is a product. A script with a filename is a trap.

Why I Document Scripts Like They're Products

Tags: Documentation, Python, Operations, Career, unlisted

I write who it is for, when to run it, what it will do twice, and where the logs live. I put a contact. If that feels heavy, the script is too important to be cute.

Future me is a user who has slept. I design for him.

Screenshots of the button

If operators run it, the doc is a picture of the button and the success sentence. If only I run it, the doc is still not optional.

Changelog

One line per behavior change. "Now idempotent on tracking number" is a gift to 6am.

Original post: https://farazrahimi.com/posts/why-i-document-scripts-like-theyre-products