I Was Sending You A Receipt, Not An Update

Every Wednesday morning you get an email from me about what changed in PodGlue that week.

I read one back a few weeks ago and it was, honestly, boring. Accurate, but boring. A list of short lines, one per thing I'd shipped. "Stop weekly community sync installing the whole monorepo." Fine. True. Means nothing to you.

I assumed it was a writing problem

My first instinct was to rewrite the email. Better headline, warmer intro, less list.

That would not have worked, and it's worth saying why.

The email is assembled automatically. Once a week a job goes and collects everything that changed, saves it, and then a second job turns that into the email. So the email can only ever be as good as what got saved.

I went and looked at what got saved. The average item was 58 characters long. The longest was 94. They were titles. Just titles.

There was nothing to write with. No amount of rewriting turns a 58 character title into something worth reading.

The reason was there and I was throwing it away

Here's the part that stung.

Every change I make has a write-up attached to it. What I changed, and why. I write it every single time. And when the weekly job went to collect the week's changes, it grabbed the title, and dropped the write-up on the floor.

Not because it was expensive to keep. It came back in the same response, at no extra cost. The code just took the one field it thought it needed and discarded the rest.

So the reason behind every single thing I shipped was being fetched and thrown away, weeks before the email was written. The email was flat because the interesting part had been deleted one layer upstream.

What the email says now

It leads with one thing we found that week, and what it meant, before it gets to the list.

Take that boring line from earlier. Here's what's underneath it:

"The Monday run died on a connection reset. The reset was ordinary flakiness. What made it fatal was that the step installed 1147 packages to get one library."

That's a story. Something broke, here's why it broke worse than it should have, here's what changed. Same event, same week. It was always there.

Two things I only caught by using real examples

I tested this against my actual write-ups rather than made-up ones, and I'm glad I did.

The first version of it picked out a note I'd left myself about merge order: "do not merge until the other one is done." Correct English, complete nonsense to anyone outside my own head. That would have gone out to every one of you as "what we found this week."

Then a reviewer caught something worse. I'd built the whole thing around my own habit of writing that label in bold. The template I actually use doesn't bold it. So the change most likely to have a good explanation, the one where I filled the form in properly, was the exact case that produced nothing at all.

Both of those are the same lesson. Test against the real thing, not the version of the real thing you have in your head.

When there's nothing to say, it says nothing

The one rule I gave myself: if there's no good finding this week, the email shows no finding. It goes back to exactly what it looked like before.

An empty box, or a heading with filler under it, is worse than not having the feature. Silence is a valid answer.

I also still see the draft on Tuesday before it goes out Wednesday, so if the automatic pick is weak, I can just fix it.

---

This one was a good reminder for me. I spend a lot of time on PodGlue making sure the story of an episode doesn't get lost between recording it and following up on it. Turns out I was losing my own story in exactly the same way: writing the reason down every week, and then quietly dropping it before anyone got to read it.

Same fix either way. Stop throwing away the part that matters.