DEV Community: Matty Stratton

I Contain Multitudes (and Also Three Git Repos)

Matty Stratton — Mon, 06 Jul 2026 01:17:28 +0000

My blog is older than most of the tools I use to run it. The oldest posts started life on LiveJournal sometime in the early 2000s, got dragged through a WordPress import at some point in the mid-2000s, spent the better part of a decade as a Hugo site, and, about a week ago, moved into an Astro 5 site that reproduces every one of those old URLs byte for byte. That's 2,630 posts spanning 2001 to 2020, frozen exactly where they landed.

At the same time, my speaking site (106 talks going back to 2012) moved off Notist and onto something I actually own. And the tool that syncs my dev.to drafts with git finally works the way it was supposed to the whole time, instead of the way it actually did for a while.

All three of those used to be separate repos. As of earlier today, they're one monorepo, with the real git history from all three preserved, not squashed into "initial commit" and called a day. Here's the tour: how the two sites work, how dev.to fits into either of them, and a couple of things that broke in interesting ways along the trip.

The shape of it today

Three systems, one person, now one repo:

mattstratton.com is the personal site. It carries the 2,630-post legacy archive and a newer, general-purpose /writing/ section for anything I want to write that isn't archival.
speaking.mattstratton.com is the talk archive: every deck, every video, every event, self-hosted.
mattstratton-dev-to isn't a website at all. It's a small tool that keeps dev.to drafts and this git repo in sync, and it's the thing that lets a post published on dev.to also show up natively on mattstratton.com, which is what's about to happen to this exact post.

They're merged into one monorepo now, but they're still three genuinely separate concerns underneath, with their own configs and their own reasons for existing. Let's take them one at a time.

mattstratton.com: preserving twenty years of receipts

The current site is Astro 5 and Tailwind v4. The single rule that shaped every other decision in the migration: URL preservation is the prime directive. astro.config.mjs sets trailingSlash: 'always' and builds in directory format specifically to reproduce the old Hugo URLs exactly, which in turn had reproduced the WordPress URLs before that. Old inbound links, whether from a 2009 blog roll or a conference site linking a talk recap from 2014, still resolve. Nobody has to fix a dead link because I decided to rewrite my site in a different framework.

The posts collection is the frozen 2001 to 2020 archive, bulk-converted from Hugo. It doesn't grow. It just needs to keep existing. Everything new goes into writing, and that one's got more going on than I expected when I started writing this post.

The field guide: my own posts plus the good stuff I wrote elsewhere

/writing/ used to be scoped much more narrowly. The working plan before this project had it locked to Postgres-focused, authority-building content, an idea inherited from a content strategy document written for a completely different audience than the one reading my personal blog. The pushback that killed that scoping was simple: I contain multitudes, and a personal site that can only hold one topic isn't really personal anymore.

What's actually interesting about /writing/ now, though, is that it isn't only my own posts. It's a merge of two genuinely different things:

Native entries in src/content/writing/, defined by the schema in content.config.ts: title, description, pubDate, topics, draft, an optional part for a curated four-part Postgres arc, and an optional canonicalUrl for when the real original lives somewhere else entirely.
A hand-maintained list of external links to posts I've written for my employer, Tiger Data, defined in field-guide.ts:

export interface FieldGuideLink {
  title: string;
  description: string;
  part: "mechanics" | "limits" | "traps" | "decision";
  url: string;
}

There are 14 of those right now, all pointing at tigerdata.com, each slotted into one of the same four part buckets native posts can opt into. writing.ts normalizes both shapes into one common GuideItem (title, description, href, external) so the template can render them identically, native entries first within each part, external links after, no interleaving by date. The one visual tell is a small "tigerdata.com ↗" badge next to external titles. No new tab, just an honest label about where you're about to land.

The newsletter: Buttondown does the sending, Astro just serves the pages

/newsletter/ works the same way as most of this site: fetch at build time, serve static files forever. buttondown.ts is an Astro content-layer loader that calls one endpoint, GET /emails?ordering=-publish_date against Buttondown's API, follows pagination until it runs out of pages, and hands the result to Astro as the newsletter collection. Every issue page, the archive index, and the RSS feed are then just static output from a normal getCollection() call, same as any local markdown file.

Two details worth calling out for anyone tempted to do the same thing:

If BUTTONDOWN_API_KEY isn't set, the loader logs a warning and returns an empty collection instead of failing the build. That's not an accident: it means anyone can clone this repo and build it locally without needing my API key.
Buttondown stores each issue's body as Markdown, so the loader runs it through marked.parse() before it ever reaches a template. The site never touches raw HTML from the API.

const key = import.meta.env.BUTTONDOWN_API_KEY ?? process.env.BUTTONDOWN_API_KEY;
if (!key) {
  logger.warn("BUTTONDOWN_API_KEY not set: newsletter archive will build empty.");
  return;
}

speaking.mattstratton.com: getting my slides back from a CDN I don't own

The old speaking site lived on Notist, and Notist had two problems that eventually became one problem: video embeds had already started quietly breaking, and every slide deck was served off Notist's CDN. The day that account lapses, the images and PDFs go with it. A core part of a speaker's professional identity, every talk I've ever given, was living in someone else's database with a thin export option.

So the new site's whole design goal is asset ownership and durability. Plain content in my own repo, on my own domain, that keeps working with no third-party dependency that can be shut off or go quietly stale. Not a redesign. A portability project.

The interesting piece is the slide pipeline, because it runs entirely locally, before a commit ever happens, and never on the deploy host:

originals/{id}.pdf --optimize(gs, 300dpi)--> public/slides/{id}.pdf --rasterize--> public/slides/{id}/{n}.webp
   (gitignored, full-res)          (committed, served, downloadable)     (committed, served, viewer images)

The reason it has to run locally: static hosts don't give you root, and you need root (or at least a real package manager) to run pdftoppm and gs. Trying to shell out to Ghostscript from inside a Netlify build is a fight you will lose. Doing the rasterization on my own machine and committing the output keeps the actual deploy build a boring, fast, host-agnostic astro build.

Video embeds got the same "own it, don't proxy it" treatment. Instead of reproducing Notist's approach (a proxy that, again, had already started breaking), each talk stores a plain provider and video ID in frontmatter, and the page renders a lightweight embed facade that only loads the real player on click.

The current numbers: 106 talks from 2012 to 2026, 93 events, 36 videos, 3,684 slide images. All of it committed, none of it one CDN outage away from disappearing.

Making the talks searchable

Video is the one asset class the speaking site doesn't fully own. It can host the reference, but not the file itself. What it can own is the transcript, and that turned into a genuinely useful feature: full-text search across every talk I've ever given.

Raw transcripts come from YouTube's auto-generated captions, pulled by scripts/transcripts.ts via yt-dlp, cleaned up, and written to public/transcripts/{id}.txt. Auto-generated captions are rough: no punctuation, mangled proper nouns, every "um" and "uh" transcribed faithfully. A transcript-cleanup Claude Code skill handles the cleanup pass, with a strict ruleset: fix punctuation, capitalization, and proper nouns, remove disfluencies, but never reword, paraphrase, or reorder anything actually said. When in doubt, the instruction is to leave the text alone rather than guess.

Search itself runs client-side against two separate JSON payloads, built at deploy time:

search-index.json.ts is small: title, abstract, event, tags, year, per talk. Loaded on first open of the search box.
deep-index.json.ts is the heavy one, concatenating each talk's transcript and slide text into a single searchable blob, fetched lazily only once you actually type a query:

const parts = [readTranscript(talk.id), readSlideText(talk.id)].filter(Boolean);
if (!parts.length) continue;
records.push({ url: talkUrl(talk), text: parts.join(" ").replace(/\s+/g, " ") });

Search.astro builds a Fuse.js fuzzy index over each payload and merges the results, so searching for a phrase I actually said mid-talk, not just a word in the title, finds the right talk. No server, no database, just two static JSON files and a fuzzy-matching library doing all the work in the browser.

Three repos become one

The three-repos-in-one-monorepo move wasn't really about tidiness. Managing three repos independently was mild friction, sure, but the actual trigger was realizing that between a frozen archive and a newly-scoped /writing/ section, there was no home left on my own site for general writing. Once that was the real problem, "merge some repos" turned into "fix the architecture, and while we're in there, get dev.to crossposting actually working."

The mechanism for the merge itself was git subtree add, not a squash and not a filter-repo rewrite. That preserves full commit history from both source repos as real, verifiable ancestry, not just "the files are here now, trust me." Both source repos were young (about 50 and 22 commits respectively), so this wasn't decades of archaeology to protect. It was doing it right on principle, which is its own kind of satisfying.

A few things bit us on the way that are worth flagging if you're ever tempted to merge repos that each bring their own CI:

GitHub Actions workflows are only discovered at the true repo root's .github/workflows/, never in a subdirectory. The dev.to workflows got left nested under the subproject's own .github/workflows/ after the initial merge, which made them completely invisible to GitHub. No error. No warning. gh workflow list just didn't show them, and they silently never ran again.
Netlify doesn't scope rebuilds by subdirectory on its own. Every push rebuilds every connected site unless you add an explicit ignore check in each site's own netlify.toml. And when Netlify skips a build for having no relevant changes, it shows that as "Canceled build due to no content change," which reads exactly like a failure in your inbox even though nothing is actually wrong.
"Base directory" and "Package directory" are different Netlify settings, and the re-link flow for a repo with no npm workspace only shows you Base directory. Package directory just never appears. Worth reading the actual docs instead of assuming, which is a sentence I apparently still need to relearn every few years.
astro check doesn't respect subproject boundaries. Run from the monorepo root, it scanned an unrelated subproject's content collections using the other subproject's generated types and produced over 200 false type errors. One explicit exclude in tsconfig.json took that down to 3, all pre-existing and unrelated.

If two or more of those apply to whatever you're about to merge, budget yourself an extra afternoon.

dev.to: ownership, not direction

The dev.to sync tool is built around one idea I'd genuinely recommend to anyone syncing content between a platform and git: ownership, not direction. The full mental model lives in the repo's CLAUDE.md, but the short version:

It's tempting to think of this as bidirectional sync, keep dev.to and git in lockstep, push changes both ways. Don't do that. It produces an endless phantom-diff loop where each side keeps thinking it's the one with the real version. Instead, a post is dev.to-owned while it's being drafted, and git ignores it entirely. Once a human merges an import PR, it's git-owned forever, marked by the presence of an id field in its frontmatter. Ownership transfers exactly once, at a deliberate moment, and it never automatically flips back.

Two small workflows do the actual work. devto-import.yml runs on a cron, pulls any newly-published dev.to posts, and opens a PR for review, never touching a file that already has an id. devto-publish.yml runs on push to files under posts/, and pushes local edits back to dev.to, writing the id back on a post's very first publish. Their domains never overlap, which is the entire point.

The crosspost pipeline (and yes, this post is going through it)

Once a post is git-owned, I can opt it into crossposting by adding crosspost: true to its frontmatter, which republishes it as a native entry in mattstratton.com's /writing/ collection and rewrites the dev.to post's canonical_url to point back at mattstratton.com, via crosspost-devto.ts. That flag only gets added after a post already has an id, meaning it's already live on dev.to. It's a deliberate, later opt-in, never part of the initial draft template. This post is a good example of the "before":

---
title: "I Contain Multitudes (and Also Three Git Repos)"
published: false
description: "..."
tags: [astro, webdev, showdev]
---

No id, no crosspost, no canonical_url. Once this is published and I decide it belongs on mattstratton.com too, it'll pick up all three, the same way decouple-release-from-deploy.md already has:

id: 4061454
date: "2026-07-03T15:43:16Z"
crosspost: true
canonical_url: "https://www.mattstratton.com/writing/decouple-release-from-deploy/"

The design detail I actually like: this collapses into one atomic commit, not a two-phase publish-then-circle-back dance. mattstratton.com's URL for a crossposted piece is fully deterministic from the filename before any build even happens. dev.to's own article ID is server-assigned and unknowable in advance. So one commit creates the new /writing/ entry and rewrites the dev.to source's canonical_url in the same diff, and one push correctly triggers both the Netlify deploy and dev.to's existing publish workflow, without anyone babysitting a second step.

One trap worth naming because it's the kind of thing that looks obviously fine until it isn't: the writing schema has had an optional canonicalUrl field since the very first Astro migration commit, for a case that had never actually come up: a native /writing/ entry that's really a copy of something whose true original lives elsewhere, like a mirrored Tiger Data post. Before the crosspost script existed, the only place that field showed up at all was a commented-out line in the placeholder template file, # canonicalUrl: ... # set when cross-posted. Nobody had ever actually set it on a real post. For a dev.to crosspost, though, mattstratton.com is becoming the canonical source, the opposite of what that field was reserved for, so the crosspost script has to know to leave it unset on the entries it generates instead of reaching for an already-named field out of habit.

A few weird-ass bugs, for flavor

This post is meant to be "here's how it's set up," not "here's a bug report," but a couple of the failures along the way are too good not to mention briefly.

The best one: the publish workflow started failing with a 422 on any post whose canonical_url changed after the first publish, with the error body {"error":"Tried to load unspecified class: Time","status":422}. Root cause was a full YAML round-trip silently dropping quotes from a timestamp that doesn't strictly need them under the JS YAML library's own rules:

# before the fix (breaks dev.to's Ruby backend)
date: 2026-07-03T15:43:16Z
# after (quoted, parses fine on both sides)
date: "2026-07-03T15:43:16Z"

Perfectly legal YAML either way, by the JS library's rules. But dev.to's backend is Ruby, and Ruby's YAML parser auto-detects that now-unquoted, ISO-8601-shaped scalar as a native Time object, which its safe loader then refuses to instantiate. Two implementations of "the same" file format, quietly disagreeing about what a bare string is allowed to become. Fixed by doing a targeted single-line replace on just the canonical_url line instead of re-serializing the whole file.

A few smaller ones, quickly:

Two files edited in a different tool picked up Windows line endings, and crosspost: true\r parses as the string "true\r", not the boolean true. Those two posts just silently never showed up as eligible.
A 7-part series had dev.to's actual Series feature turned on for exactly 2 of the 7 posts, predating any of this tooling.
Rewriting internal links across that same series hit a substring-replace bug where a typo'd slug happened to be a literal prefix of a different, correct slug. Fixed by sorting replacements longest-slug-first.

The fun stuff: memory and gains

Two smaller pieces worth a callout because they're genuinely neat and don't fit anywhere else in this tour.

The speaking site's Claude Code skills (adding a new talk, cleaning up a transcript, resyncing talk memory) don't need memory.build to work. They ran fine without it. But they now also include it, a permanent memory layer for AI agents, so that when I'm working with an agent on content, it can pull up what it already knows about a talk or a previous session instead of me re-explaining context every single time. Nice to have, not load-bearing.

And /fitness pulls my workout history straight from Liftosaur's API at build time. The reason it exists at all: Liftosaur's own public profile page just didn't show as much as I wanted, no real trend view, nothing I could link people to that told the whole story. Liftosaur doesn't hand back tidy JSON for a workout either; it returns a compact Liftoscript-text blob, so a small parser extracts the date, program, exercises, and sets from that text. Personal records and trend sparklines get computed from that parsed data at render time, not fetched as a separate call.

What's still on my plate

The crosspost trigger right now is a manual CLI command I have to remember to run. The fix I actually want: since the dev.to workflow is already entirely PR-centric (import arrives as a PR, id gets written back as an auto-commit on that same push, never a second spawned PR), the crosspost step should follow the exact same shape. A GitHub Action on pull_request that detects crosspost: true, generates the /writing/ entry, and pushes it as an additional commit onto the same PR, instead of a manual script run or a redundant second PR. I filed an issue for it while writing this post, because I'd apparently been assuming for a while that one already existed and it hadn't.

A couple of others I'm actually looking forward to: a map of everywhere I've spoken on the speaking site (the event data already has lat/lng, so this should be a fun afternoon, not a project), and real hero and thumbnail image design for /writing/ and the legacy archive, since the crosspost script currently papers over that gap by embedding the cover image inline in the post body instead of rendering it properly. There's also the usual pile of housekeeping (a master to main rename, a Node 24 upgrade) that's real but not exactly a fun read.

None of it was urgent enough to hold up shipping the parts that already work. That's usually how the good list gets built anyway.

Your Agent Didn't Break Prod. Your Pipeline Did.

Matty Stratton — Fri, 03 Jul 2026 15:43:16 +0000

Picture a pipeline that looks pretty reasonable on paper. An agent opens pull requests. CI gates the merge to main: lint, tests, build, all green or it doesn't land. A scheduled job periodically promotes whatever's sitting in staging straight to production. No individual approval per feature. Just a batch cutover on a timer.

That pipeline will absolutely, eventually, wreck your week.

Not because the agent did anything malicious. Because two very different questions got quietly collapsed into one gate: "did this pass CI" and "is this safe for a real person to see right now." Those have never been the same question, not for humans and not for robots. We just used to have enough friction in the deploy process that the gap between them rarely mattered.

I've written before about the scaffolding that lets a non-engineer safely drive a coding agent against a real codebase. Rules, skills, hooks. Three layers of paranoia built into the system instead of relying on any one person's vigilance on a random Friday. That post was about the merge gate: what stops garbage from landing on main.

Part of that merge gate is worth calling out on its own: a second pass on the same PR, same harness, different system prompt, catches things the first pass missed. You don't need a different vendor or a different model for that to work, just a fresh set of eyes that didn't write the code. I wrote more about why that works here.

This post is about the gate after that one. Passing CI and landing on main solves exactly one problem, and it is not the problem of "will my users see something half-finished this afternoon."

I've been talking about shifting things left in the pipeline for the better part of a decade, usually about security. Same instinct, one checkpoint further down the line: not just "is this code safe to merge," but "is deploying this code, right now, safe."

Continuous delivery is not continuous deployment

This isn't a new idea. It's an old one that a lot of teams politely ignored for a decade, mostly because deploys used to be scary enough that nobody wanted to do more than one a sprint.

Continuous delivery means every merge is releasable. It does not mean every merge is released. Continuous deployment collapses those two things into the same action, and that's a choice you make on purpose, not a default you inherit by moving fast.

If your pipeline treats "merged" and "live" as synonyms, you've opted into continuous deployment without ever deciding to. The fix isn't slowing the pipeline down. It's separating the two decisions so a merge event and a "customers can see this" event stop being the same button.

Feature flags are one popular way to do that separation, and if you already run one, great, keep running it. But a flag is a mechanism, not the point. I don't run a feature-flag system myself, and I still get the same separation. What matters is the decoupling, not the specific tool you use to get it.

In case it's not obvious what one even looks like: a feature flag, at its most embarrassingly simple, is a boolean and an if statement.

if (flags.newInvoiceExport) {
  renderNewExport()
} else {
  renderOldExport()
}

You do not need a vendor with a pricing page to get started. A config value, an environment variable, a column on a settings table, all of that counts as day one. Upgrade to something like LaunchDarkly or Unleash once the dumb version is the thing slowing you down, not before.

Put a gate on the release event, not just the merge event

My own setup looks like this: PRs merge to main, but main isn't what's live. A separate release step promotes main to a production branch, and that promotion only happens after I explicitly say go. Nothing gets pushed to production on a timer, and nothing gets pushed because a batch of unrelated changes happened to be sitting around.

Once that promotion kicks off, it isn't done just because Vercel says "build succeeded." The release process waits until Vercel confirms the new build is actually the one serving traffic, then runs an automated check against production itself: hit a handful of endpoints that have to work, confirm they do, and only then call the release finished. If that check fails, I find out. A user does not.

There's a second, slower layer after that: a manual pass through the specific things that changed in this release, because an automated check can tell you the server responds, not that the feature behaves the way you meant it to.

None of that requires a flag anywhere. The gate isn't "does this code know how to hide itself." The gate is "does a human, and then a machine, and then a human again, all get a chance to say no before this reaches a real user." Feature flags earn you a fourth layer, an inside-the-code one, on top of that. Nice to have. Not the load-bearing part.

An automated check is monitoring with a head start

I've spent a lot of years on the incident response and observability side of this industry, enough to have given entire talks on it. The lesson that refuses to go out of style: an automated check after a release doesn't exist to catch every possible bad deploy. It exists to catch the slow discovery of a bad deploy.

A user hitting your bug is monitoring too. It's just the worst possible kind, because you find out from a support ticket instead of a dashboard, and by the time the ticket lands, it's already been somebody's bad afternoon for a while.

A post-deploy check that hits the handful of things that actually matter isn't a replacement for real observability: dashboards, alerts, tracing, whatever you've already built. It's a compressed version of the same instinct, aimed at the exact moment you're most likely to have broken something, which is right after you changed something.

The fallback: revert fast, and don't paint yourself into a corner

A release gate handles the "I'm not ready" case. It doesn't handle the "I was wrong" case, where the promotion went through, real users saw it, and it turns out there's a bug that only shows up under actual traffic. For that you need the other half: the ability to revert fast, which mostly comes down to one boring rule.

Don't ship a database migration that the previous version of your code can't survive.

This is the expand/contract pattern, and if you've been doing this long enough you've relearned it under a new name roughly every three years. Add the new column nullable. Backfill it. Write to both the old and new column. Read from the new one once you trust it. Only then, in a later release, drop the old column. Every step in that sequence is safe to roll back from, because the previous version of the app never depends on something that doesn't exist yet.

Skip that discipline and your revert button becomes decorative. You can git revert the code in about four seconds. If the migration already ran and already dropped a column the old code expects, reverting the code just gives you a fancier way to be down.

This is also, not coincidentally, incident response 101. Effective incident response runs on having a small number of pre-agreed moves you can execute without a meeting: revert, roll back, page someone, whatever applies. The worst possible moment to invent your rollback plan is during the incident it's supposed to fix. If reverting requires an engineer to reason live about which of three interdependent migrations is safe to undo, you don't have a rollback plan. You have a discussion topic, and discussion topics don't resolve outages.

Someone still has to own saying "go"

None of the automation above changes who's accountable for a release. It changes what that person is accountable with.

I've talked before, on stages instead of on a blog, about how the lifecycle of a service doesn't end the moment something reaches production, and ownership doesn't evaporate the second it ships. Somebody owns a service in production the same way somebody owns the decision to promote a build to it. If your team can't answer "who decided to release this" for a given deploy, an agent that opens PRs quickly is not actually your biggest problem.

In my setup, that person is me, for now. It might be someone else on my team next month, and the gate doesn't care which name is attached, only that a name is. The promotion step has an owner. It is never "whichever cron job happened to fire at 3am."

Same guardrails, new reason to need them

None of this is agent-specific. Gated promotions, expand/contract migrations, decoupling deploy from release: this is stuff engineering orgs have known for well over a decade. It got treated as optional at a lot of small teams because a human was in the loop on every deploy, and a human noticing "wait, this doesn't feel done yet" was doing the job the gate should have been doing.

Take that human out of the loop, or just make them faster and more numerous by handing them an agent, and the discipline you skipped stops being optional. It was never really optional. It was just being covered for by somebody's judgment call at 4:58pm on a Thursday.

The agent didn't create this problem. It just removed the friction that used to hide it.

Same as last time: if you want the receipts on how the merge-side guardrails work, that's here. This one's the other half.

What's Actually in My .zshrc (and Why)

Matty Stratton — Wed, 01 Jul 2026 15:39:44 +0000

Your shell config is mostly a graveyard. A line you added in 2019 to fix a problem you don't remember having. An alias you're afraid to remove because what if you need it. Mine is no different, but there are a handful of pieces in there that are worth explaining, not because they're clever, but because most people have never thought about why they'd want them.

This isn't a full dump of my config. If you want that, it's all on GitHub at matty-dotfiles. This post is about the config itself: the logic, the functions, the stuff that changes how the shell behaves depending on who, or what, is actually running it. (There's a quick note at the bottom on how the files are actually organized, if you're wondering why I keep saying "files" instead of "file.")

The part that actually matters: AGENT_MODE

Here's the thing that made me want to write this post in the first place.

if [[ -n "$npm_config_yes" ]] || [[ -n "$CI" ]] || [[ "$-" != *i* ]]; then
  export AGENT_MODE=true
else
  export AGENT_MODE=false
fi

Your shell used to have one audience: you. That's not true anymore. If you're running Claude Code, or any other coding agent that shells out to run commands on your behalf, your shell now has a second audience that doesn't want the same things you do. It doesn't want thefuck to interactively suggest a correction. It doesn't want a confirmation prompt before rm deletes something. It doesn't want your fancy multi-line prompt burning tokens or confusing a parser.

So I detect it. If npm_config_yes is set, or CI is set, or the shell isn't interactive ($- doesn't contain i), I flip AGENT_MODE on. Later in .zshrc_shared, that flag does real work:

if [[ "$AGENT_MODE" == "true" ]]; then
  export EDITOR='nvim'
  PROMPT='%n@%m:%~%# '
  RPROMPT=''
  unsetopt CORRECT
  unsetopt CORRECT_ALL
  setopt NO_BEEP
  setopt NO_HIST_BEEP
  setopt NO_LIST_BEEP
  alias rm='rm -f'
  alias cp='cp -f'
  alias mv='mv -f'
  alias npm='npm --no-fund --no-audit'
  alias yarn='yarn --non-interactive'
  alias pip='pip --quiet'
  alias git='git -c advice.detachedHead=false'
fi

No beeps, no interactive confirmations, a boring flat prompt instead of starship, and force flags on the destructive file commands so an agent doesn't get stuck at a prompt it can't answer. EDITOR switches to plain nvim instead of code --wait, because a headless agent trying to wait on VS Code to close a file is not a fun afternoon.

I'd bet a decent chunk of you reading this have never thought about the fact that your interactive shell defaults are actively hostile to a non-interactive process. Worth fixing before it bites you.

Secrets that don't live in plaintext

source ~/keychain-environment-variables.sh

export GITHUB_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export CHANGELOG_GITHUB_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export BOWIE_GITHUB_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export HOMEBREW_GITHUB_API_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export GITHUB_PERSONAL_ACCESS_TOKEN=$(keychain-environment-variable GITHUB_TOKEN)
export BUTTONDOWN_API_KEY=$(keychain-environment-variable BUTTONDOWN_API_KEY)

keychain-environment-variable is a function that pulls a secret out of macOS's Keychain at shell startup instead of having it sit around in plaintext in a dotfile that's synced to GitHub. I did not write this myself, I adapted it from a blog post, and I only know that because the comment at the top of the file still says so. It just shells out to security find-generic-password under the hood, nothing exotic, but it means the thing I git push never has a credential in it.

It's worth calling out that this function has to live somewhere. It's not in .zshrc_shared itself, it's a separate file (keychain-environment-variables.sh) that gets sourced, and yes, it's yadm-alternated too (##os.Darwin and ##os.Linux versions, same symlink dance as the zshrc files). If you go copy the alias/export lines above without also grabbing that script, none of this works. Ask me how I know.

The `gh` alias that fixes a dumb problem

alias gh="GITHUB_TOKEN= command gh"

Small, but it earns its place. The gh CLI has its own auth flow, and it checks GITHUB_TOKEN first if it's set, which it is, everywhere, because half my other tools need it exported. Without this alias, gh quietly uses that token instead of my actual gh auth login session, and I get weird permission mismatches that take way too long to debug. This alias just unsets the variable for the one command that has opinions about it.

A shortcut for working an issue with Claude Code

issue() { claude --permission-mode plan -w "issue-$1" "/implement issue #$1" }

Type issue 412 and it spins up Claude Code in plan mode, in its own worktree named issue-412, already pointed at a slash command that implements GitHub issue #412. It's a one-liner, but it's the kind of one-liner that removes enough friction that I actually use it instead of doing the same five commands by hand every time.

atuin and starship deserve more than a name-drop

I mentioned in My Brewfile that I install both of these, but I glossed over why, so let's fix that.

eval "$(atuin init zsh)"

atuin replaces your plain old shell history file with a searchable SQLite database, and it hooks into your shell so every command gets logged with context: what directory you were in, how long it ran, whether it exited cleanly. The part that actually changed how I work is the search. Instead of mashing the up arrow forty times or grepping through .zsh_history and hoping, I hit a keybinding and fuzzy-search across every command I've ever run, filtered by directory if I want. If you sync it, that history follows you across machines too. I didn't realize how much time I spent reconstructing commands from memory until I stopped having to.

eval "$(starship init zsh)"

starship is the prompt. That's it, that's the whole job, but it does that job well: git branch and status, language versions, command duration, all rendered fast and only when relevant, so it doesn't clutter the prompt with things that don't apply to the directory you're in. The reason it matters more than "cosmetic" makes it sound is that a good prompt answers questions before you have to ask them. Am I in a dirty git tree? Which Node version is active here? Starship tells me before I type anything.

Also notice that starship shows back up in the AGENT_MODE block from earlier, sort of. When agent mode is on, I explicitly override PROMPT to something flat and boring instead of letting starship render. Fancy prompts are a UX win for a human; they're just noise (or worse, a parsing hazard) for a process reading your terminal output.

Aliases are underrated, actually

People treat aliases like a beginner's trick, something you graduate out of once you "really" know the shell. That's backwards. An alias is just muscle memory you get to define yourself, for the commands you actually run, not the ones a tutorial thinks you should run. A few from my shared config:

alias c='clear'
alias sz='source ~/.zshrc'
alias zshconfig="nvim ~/.zshrc"
alias gpom="git push origin main"
alias gitmain="git checkout main && git pull origin main"
alias cpenv='cp ~/src/github.com/timescale/tiger-den/.env ./'

c has been in my shell configs for so many decades at this point that I genuinely forget, in the moment, that c isn't actually a real command. It's clear. It has always been clear. I have simply stopped knowing that.

sz and zshconfig exist because I edit and reload this file constantly, and typing nvim ~/.zshrc##os.Darwin correctly every time is not a skill I've bothered to develop. gpom and gitmain are the ones I'd actually recommend you steal: they encode the exact git incantations you run dozens of times a day into something you can type without thinking. cpenv is hyper-specific to one project of mine, and that's fine too. Aliases don't need to be generalizable to be worth having.

The stuff I'll just mention

A few plugins and settings that do work but don't need a full section: thefuck for command correction, autojump for directory jumping, oh-my-zsh plugins like git-extras and history-substring-search, and a couple of bindkeys so option+arrow jumps by word instead of doing nothing useful:

bindkey "^[[1;3C" forward-word
bindkey "^[[1;3D" backward-word

All small. All the kind of thing you only notice once it's gone.

Bonus: why there are three files, not one

I manage my dotfiles with yadm, which supports "alternate files" keyed on things like OS. So instead of one .zshrc, I actually have .zshrc##os.Darwin and .zshrc##os.Linux, and yadm symlinks the right one to .zshrc depending on the machine. Both of those source a third file, .zshrc_shared, which holds everything that doesn't care what kernel it's running on. Same setup applies to the keychain script above.

That's really it. It's a small mechanism, not a deep one, which is exactly why it's a bonus section and not its own post. If enough people want the full "how yadm alternates work" writeup, say so in the comments and I'll do it properly.

Go poke around

The full files are in matty-dotfiles if you want the parts I skipped. If you've got a shell trick worth stealing, I want to hear about it in the comments.

Postgres Extensions Cheat Sheet: Replace 7 Databases With SQL

Matty Stratton — Sat, 02 May 2026 20:47:24 +0000

This post is a practical companion to It's 2026, Just Use Postgres. That post makes the architectural case for consolidating on Postgres. This one shows you how.

Below are working SQL examples for each use case. Every extension listed here is available on Tiger Cloud with no additional setup. If you're self-hosting, each section links to the extension's repo.

What you'll be able to do after reading this: Set up Postgres extensions for full-text search, vector search, time-series, caching, message queues, document storage, geospatial queries, and scheduled jobs. Each section is self-contained, so you can skip to what you need.

Enable Everything

Here's the full set. You probably don't need all of them. Pick the ones that match your workload.

CREATE EXTENSION pg_textsearch; -- BM25 full-text search
CREATE EXTENSION vector; -- Vector search (pgvector)
CREATE EXTENSION vectorscale; -- DiskANN index for vectors
CREATE EXTENSION ai; -- AI embeddings and RAG workflows
CREATE EXTENSION timescaledb; -- Time-series
CREATE EXTENSION pgmq; -- Message queues
CREATE EXTENSION pg_cron; -- Scheduled jobs
CREATE EXTENSION postgis; -- Geospatial

Full-Text Search (Replace Elasticsearch)

Extension: pg_textsearch (true BM25 ranking)

What you're replacing: Elasticsearch (separate JVM cluster, complex mappings, sync pipelines), Solr, or Algolia ($1 per 1,000 searches).

What you get: The same BM25 algorithm that powers Elasticsearch, running natively in Postgres. No separate cluster. No sync jobs. No data drift.

CREATE TABLE articles (
  id SERIAL PRIMARY KEY,
  title TEXT,
  content TEXT
);

-- Create a BM25 index
CREATE INDEX idx_articles_bm25 ON articles USING bm25(content)
  WITH (text_config = 'english');

-- Search with BM25 scoring
SELECT title, -(content <@> 'database optimization') AS score
FROM articles
ORDER BY content <@> 'database optimization'
LIMIT 10;

Deep dive: You Don't Need Elasticsearch: BM25 is Now in Postgres

Vector Search (Replace Pinecone)

Extensions: pgvector + pgvectorscale

What you're replacing: Pinecone ($70/month minimum, separate infrastructure, data sync), Qdrant, Milvus, or Weaviate.

What you get: pgvectorscale uses the DiskANN algorithm (from Microsoft Research). On a 50M vector benchmark, it achieved 28x lower p95 latency and 16x higher throughput than Pinecone at 99% recall.

CREATE EXTENSION vector;
CREATE EXTENSION vectorscale CASCADE;

CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding vector(1536)
);

-- High-performance DiskANN index
CREATE INDEX idx_docs_embedding ON documents USING diskann(embedding);

-- Find similar documents
SELECT content, embedding <=> '[0.1, 0.2, ...]'::vector AS distance
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector
LIMIT 10;

Auto-sync embeddings with pgai

No more manual embedding pipelines. pgai regenerates embeddings automatically on every INSERT and UPDATE.

SELECT ai.create_vectorizer(
  'documents'::regclass,
  loading => ai.loading_column(column_name => 'content'),
  embedding => ai.embedding_openai(
    model => 'text-embedding-3-small',
    dimensions => '1536'
  )
);

Every row stays in sync. No batch jobs. No drift.

Hybrid Search: BM25 + Vectors in One Query

This is where Postgres consolidation pays off immediately. Combining keyword search and semantic search in other stacks requires two API calls, result merging, failure handling, and double the latency. In Postgres, it's one query.

Simple weighted hybrid

SELECT
  title,
  -(content <@> 'database optimization') AS bm25_score,
  embedding <=> query_embedding AS vector_distance,
  0.7 * (-(content <@> 'database optimization')) +
  0.3 * (1 - (embedding <=> query_embedding)) AS hybrid_score
FROM articles
ORDER BY hybrid_score DESC
LIMIT 10;

Reciprocal Rank Fusion (for RAG applications)

WITH bm25 AS (
  SELECT id, ROW_NUMBER() OVER (ORDER BY content <@> $1) AS rank
  FROM documents LIMIT 20
),
vectors AS (
  SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> $2) AS rank
  FROM documents LIMIT 20
)
SELECT d.*,
  1.0 / (60 + COALESCE(b.rank, 1000)) +
  1.0 / (60 + COALESCE(v.rank, 1000)) AS score
FROM documents d
LEFT JOIN bm25 b ON d.id = b.id
LEFT JOIN vectors v ON d.id = v.id
WHERE b.id IS NOT NULL OR v.id IS NOT NULL
ORDER BY score DESC LIMIT 10;

One query. One transaction. One result set.

Time-Series (Replace InfluxDB)

Extension: TimescaleDB (21K+ GitHub stars)

What you're replacing: InfluxDB (separate database, Flux or limited SQL), Prometheus (metrics only, not application data).

What you get: Automatic time-based partitioning, compression up to 95%, continuous aggregates for fast dashboards, and full SQL. Your time-series data lives alongside your relational data with JOINs and ACID guarantees.

CREATE EXTENSION timescaledb;

CREATE TABLE metrics (
  time TIMESTAMPTZ NOT NULL,
  device_id TEXT,
  temperature DOUBLE PRECISION
);

-- Convert to a hypertable (automatic time partitioning)
SELECT create_hypertable('metrics', 'time');

-- Query with time buckets
SELECT time_bucket('1 hour', time) AS hour,
       AVG(temperature)
FROM metrics
WHERE time > NOW() - INTERVAL '24 hours'
GROUP BY hour;

Lifecycle automation

TimescaleDB handles retention and compression policies so you don't have to build cron jobs for data management.

-- Automatically drop data older than 30 days
SELECT add_retention_policy('metrics', INTERVAL '30 days');

-- Compress data older than 7 days (up to 95% storage reduction)
ALTER TABLE metrics SET (timescaledb.compress);
SELECT add_compression_policy('metrics', INTERVAL '7 days');

Case study: Plexigrid went from 4 databases to 1 and got 350x faster queries.

Caching (Replace Redis)

Feature: UNLOGGED tables + JSONB (built into Postgres, no extension needed)

What you're replacing: Redis for simple key-value caching scenarios.

What you get: In-memory-speed storage without WAL overhead. Good for session data, temporary lookups, and simple caches. No separate service to operate.

When to keep Redis: If you need pub/sub, sorted sets, Lua scripting, or complex data structures, Redis is still the better tool for those specific jobs.

-- UNLOGGED = no WAL overhead, faster writes
CREATE UNLOGGED TABLE cache (
  key TEXT PRIMARY KEY,
  value JSONB,
  expires_at TIMESTAMPTZ
);

-- Set with expiration
INSERT INTO cache (key, value, expires_at)
VALUES ('user:123', '{"name": "Alice"}', NOW() + INTERVAL '1 hour')
ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;

-- Get
SELECT value FROM cache
WHERE key = 'user:123' AND expires_at > NOW();

-- Schedule cleanup with pg_cron
SELECT cron.schedule('cache_cleanup', '0 * * * *',
  $$DELETE FROM cache WHERE expires_at < NOW()$$);

Message Queues (Replace Kafka)

Extension: pgmq

What you're replacing: Kafka or RabbitMQ for task queues and simple event processing.

What you get: A lightweight message queue inside Postgres. Send, receive with visibility timeouts, and delete after processing. Transactional with the rest of your data.

When to keep Kafka: If you need high-throughput event streaming across dozens of services, consumer groups, exactly-once semantics, or multi-datacenter replication, Kafka is purpose-built for that.

CREATE EXTENSION pgmq;
SELECT pgmq.create('my_queue');

-- Send a message
SELECT pgmq.send('my_queue', '{"event": "signup", "user_id": 123}');

-- Receive (with 30-second visibility timeout)
SELECT * FROM pgmq.read('my_queue', 30, 5);

-- Delete after processing
SELECT pgmq.delete('my_queue', msg_id);

Alternative: SKIP LOCKED pattern (no extension needed)

For simple job queues, Postgres has a built-in pattern using FOR UPDATE SKIP LOCKED:

CREATE TABLE jobs (
  id SERIAL PRIMARY KEY,
  payload JSONB,
  status TEXT DEFAULT 'pending'
);

-- Worker claims a job atomically
UPDATE jobs SET status = 'processing'
WHERE id = (
  SELECT id FROM jobs WHERE status = 'pending'
  FOR UPDATE SKIP LOCKED LIMIT 1
) RETURNING *;

Documents (Replace MongoDB)

Feature: Native JSONB (built into Postgres since 2014)

What you're replacing: MongoDB for document storage.

What you get: Schemaless document storage with GIN indexing, plus everything Postgres gives you: ACID transactions, relational JOINs, and SQL. No separate database for your "document-shaped" data.

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  data JSONB
);

-- Insert a nested document
INSERT INTO users (data) VALUES ('{
  "name": "Alice",
  "profile": {"bio": "Developer", "links": ["github.com/alice"]}
}');

-- Query nested fields
SELECT data->>'name', data->'profile'->>'bio'
FROM users
WHERE data->'profile'->>'bio' LIKE '%Developer%';

-- Index specific JSON fields for fast lookups
CREATE INDEX idx_users_email ON users ((data->>'email'));

Geospatial (Replace Specialized GIS)

Extension: PostGIS (the industry standard since 2001)

What you're replacing: Nothing, really. PostGIS is what most specialized GIS tools are built on. It powers OpenStreetMap and has been in production for 24 years.

CREATE EXTENSION postgis;

CREATE TABLE stores (
  id SERIAL PRIMARY KEY,
  name TEXT,
  location GEOGRAPHY(POINT, 4326)
);

-- Find stores within 5km
SELECT name,
  ST_Distance(location, ST_MakePoint(-122.4, 37.78)::geography) AS meters
FROM stores
WHERE ST_DWithin(location, ST_MakePoint(-122.4, 37.78)::geography, 5000);

Scheduled Jobs (Replace External Cron)

Extension: pg_cron

What you're replacing: External cron jobs, Kubernetes CronJobs, or Lambda scheduled triggers for database maintenance tasks.

What you get: Cron scheduling inside Postgres. Useful for cache cleanup, materialized view refreshes, data retention, and periodic aggregation.

CREATE EXTENSION pg_cron;

-- Run cache cleanup every hour
SELECT cron.schedule('cleanup', '0 * * * *',
  $$DELETE FROM cache WHERE expires_at < NOW()$$);

-- Refresh a materialized view every night at 2 AM
SELECT cron.schedule('rollup', '0 2 * * *',
  $$REFRESH MATERIALIZED VIEW CONCURRENTLY daily_stats$$);

Fuzzy Search (Typo Tolerance)

Extension: pg_trgm (built into Postgres)

CREATE EXTENSION pg_trgm;

CREATE INDEX idx_name_trgm ON products USING GIN (name gin_trgm_ops);

-- Finds "PostgreSQL" even when typed as "posgresql"
SELECT name FROM products
WHERE name % 'posgresql'
ORDER BY similarity(name, 'posgresql') DESC;

What's Next

If you want the architectural argument for why consolidating on Postgres matters (especially in the AI era), read It's 2026, Just Use Postgres.

All of these extensions come pre-configured on Tiger Cloud. Create a free database and start building.

Further reading:

Why I'm Learning ROS 2 as a Database Person

Matty Stratton — Fri, 01 May 2026 21:46:47 +0000

There's a moment that happens in every robotics company that makes it to production. The pilot worked. The robot does the thing. Now there are twenty on the floor, then fifty, then a fleet, and somebody asks: "What did the sensors look like on unit 17 during those three anomalies last quarter?"

That's when the data infrastructure question gets real. As robotics moves from lab to warehouse floor to factory line, that question is going to come up a lot more often. The default answers aren't really built for it.

I'm not a robotics engineer. Never built a robot. Never written a ROS 2 node or had an argument about MCAP vs. SQLite3 (though I'm about to). What I am is someone who's spent 20+ years watching what happens when storage decisions get made before the questions are fully understood. Log files are the classic version: great for appending, bad for answering "show me the error pattern across 200 servers from three weeks ago." The data exists. It's just not queryable. That's the shape of regret I'm talking about.

I work at Tiger Data doing developer relations for TimescaleDB. Time-series data is literally my job. When I started looking at how ROS 2 handles recorded telemetry at scale, I saw something familiar: high-frequency sequential writes, stable append rates, a recording format optimized for replay rather than analysis, no real query story for "compare behavior across 200 runs without loading everything into memory."

Oof.

rosbag2 is good at what it does. Record, replay, done. That's the right scope for it. If you've been running ROS 2 long enough to think about what happens after the bag file, you've probably felt the edge of that scope. The problem is that "done recording" is the beginning of a different problem when you're trying to understand what's happening across a fleet, over time, at scale. There's an open feature request in the rosbag2 repo that names TimescaleDB and InfluxDB by name as candidate options for exactly this. It's been open since July 2024. Zero comments.

The community noticed the gap. Nobody filled it.

So that's what I'm going to try to figure out, in public. I'm going to build a ROS 2 node that writes telemetry directly to TimescaleDB and actually query it. All of it in a public GitHub repo, commit by commit, so the decisions are visible as they get made. Document everything that breaks. The database side I know. The ROS 2 side I'm learning from scratch, and I'll be honest about that difference in real time. And to be clear: I don't actually know what any of this looks like at fleet scale. That's not false modesty. That's the whole point.

What's coming next: getting the local environment set up (TurtleBot3 is basically the hello world of ROS 2 simulation: it's what the official tutorials use, it publishes the standard topics I care about, and Gazebo runs the whole thing without me needing actual hardware*) and a post on what rosbag2 actually stores and why the format question matters once you're past replay. After that, the actual build: schema decisions, type mapping headaches, and a Grafana dashboard over live robot telemetry. The full tutorial comes last, once I've learned enough to actually teach it.

If you've ever wanted to weigh in on that rosbag2 feature request, now's a good time. And if you're working on this problem (fleet telemetry pipelines, robot data at scale, the gap between recording and understanding), I want to hear what you're running into.

* - that said, I am not opposed to asking my boss to buy me a robot

How My Coworker Who Didn't Know 'cd' Shipped to Production

Matty Stratton — Thu, 23 Apr 2026 20:30:39 +0000

This morning, our Design Lead asked me how to get her terminal into the right folder.

Tanya [6:57 AM]
my ghost isnt in tiger den anymore! GAH do i do /tiger-den
or what was the command to make it work 
in tiger den

Matty [7:14 AM]
What what?

Tanya [7:14 AM]
sorry lol
you know when i go into terminal/or ghostie
and i need to type the thing to make it so im
working in tiger den

Matty [7:14 AM]
Yes type cd tiger-den

Tanya [7:15 AM]
YES
OK CD
thank you

Tanya has been here at Tiger Data for about two weeks. In that time, she shipped a feature to our production Next.js app.

I'm not going to pretend that's a normal sentence to write.

Tanya is our Design Lead. She runs brand. She's the reason our designs look the way they do and our blog thumbnails don't look like a high school yearbook. She is not a software engineer. She had not, as far as I know, previously planned on becoming one.

She didn't become one. She just started shipping.

The feature she shipped is an internal brand hub: a searchable index of every Tiger Data brand asset (logos, typography, colors, whatever you need) plus an interactive image builder that works like Canva (if Canva had been written specifically for our team). You can upload your own images, pick from our logo library, layer in backgrounds and icons, and drop text on top. Drag everything around, resize it, line it up. Export a PNG. (The thumbnail on this post was made with it.)

The downside of teaching a designer to use the terminal is that she will want hers to look like yours. Tanya saw my Ghostty theme and my catppuccin Starship theme over a screen share and decided she wanted both. Her Claude Code statusline came next. That's an entire other post.

Hold both of these facts in your brain at the same time: Tanya is asking me what cd does this morning. Tanya shipped a real feature to a real codebase last week.

If you read my last post on coding agents and internal tooling, you know where I ended it. The caveat was that I was a solo contributor to a real codebase, and the first comment on the post called out exactly the right thing. Who owns this when you leave? That's a reasonable question. In March, my answer was "me, and that's a problem."

My answer in April is "...and also Tanya."

That's only true because of what got built alongside the agent. The agent is the interesting part of the demo. The boring part is what made it safe to hand a Next.js codebase to a designer who's still learning cd.

Here's that boring part.

The agent is not the hard part

Coding agents are very good at a lot of things. Being trustworthy is...not one of them.

I don't mean malicious. I mean if you ask an agent to fix a bug, it will often fix the bug. It will also sometimes decide the failing test is "probably flaky" and move on. Or notice a test it doesn't understand and quietly skip it. Or hit an error, try a second approach, fail, try a third approach, fail again, and by the time you look up it has deleted the function you were trying to fix. Or my favorite one: "These test failures are unrelated to my changes".

This is catchable. I catch a lot of it. I've been doing ops since before the Seinfeld finale aired, and I have been running DevOpsDays since before most of the current DevOps job descriptions existed. I read every diff before it leaves my machine and I have strong opinions about what a normal-looking CI run is supposed to contain.

I still miss things, everyone does. I rubber-stamp, I push tired, I get three levels deep on a task and stop reading carefully. Even with the paranoia cranked up, I am not reliably the last line of defense for my own work, let alone anyone else's.

And the paranoia itself is not transferable. "Notice when an agent silently dropped a test case" is not a skill you pick up in two weeks. It is not a skill most of the engineers I know pick up in two weeks, because most of them never had to. I cannot hand it to Tanya by writing a memo.

So the question is not how do I make Tanya as paranoid as I am. The question is: how do I make the system so paranoid that it doesn't matter how paranoid any of us are on a given Friday afternoon?

You build the paranoia into the system. (If this sounds familiar, it should.)

Rules are a suggestion

The first place everyone reaches is CLAUDE.md. Some people call theirs AGENTS.md if they want the file to be portable across agents that aren't Claude. Same idea. You write down the rules you want the agent to follow, drop it at the root of the repo, and the agent reads it every session.

Ours has a section called "Golden Rules". A handful of the actual rules from the actual file:

Diagnose before fixing. Read errors, trace code, explain your hypothesis before writing any fix. No guess-and-deploy.

Never dismiss failures. Test failures, CI failures, lint warnings. Investigate every one. Never call them "pre-existing" or "not my problem."

Never destructive without permission. No DROP, TRUNCATE, DELETE without WHERE.

Always use /pr to push. Never raw git push.

These are not theoretical. Each one is on the list because the agent did the thing I didn't want it to do, often enough that I eventually wrote it down. (Sometimes from running /insights in Claude Code.)

Does the agent follow them? Mostly. Does the agent ignore them when convenient? Also yes.

The failure mode is an exchange you have probably already had:

Me: "Wait, you just pushed to main."

Claude: "Oh shoot, you're right. The CLAUDE.md says to use /pr. I just... didn't."

It apologizes. It means it. It will still do it again on Tuesday.

CLAUDE.md is training; it shapes the default behavior. It does not enforce anything. Treat it like training and it is useful. Treat it like a wall and something is going to walk through the wall.

That was the first thing I had to learn. It might have take a few times.

Skills are a habit

If rules are what you write down when you want an agent to know something, skills are what you write down when you want the agent (or the human) to do something the same way every time.

A Claude Code skill is roughly: a folder with instructions, some scripts, and a slash command. Type /setup and it walks through our dev environment setup. Type /debug and it starts a structured investigation instead of letting the agent flail. Type /release and it runs the release process in the right order.

The one that matters most is /pr.

Our repo has a preflight checklist you have to pass to open a pull request. It runs lint. It runs the typechecker. It runs the tests. It runs the build. It runs a code review subagent. If any changed files touch rendered output, it runs a UI verification step. If any touched docs, it runs a docs-drift check. If any touched security-sensitive paths, it runs a security review. Only then does it actually open the PR, and even then it opens it as a draft.

All of that is one command. Tanya does not have to remember any of it. She types /pr.

This is still not enforcement. Skills are suggestions. A motivated human (or a tired agent, or a confused agent, or an agent being nudged by a tired human) can skip /pr and push directly, and nothing in the skill itself will stop them (note: the skill does try to tell the agent when it should try to run it, and it usually gets it right...but not always).

The job of a skill is to make the right way the easy way. /pr is one command. Running all of those checks by hand is eight. If typing /pr is easier than doing the alternative, the alternative stops happening. That is most of the game.

Tanya used /pr for the brand hub. She did not run lint, typecheck, tests, and build in sequence. She would not have known to! She typed a slash and a word. Everything ran.

The rest is between her and the agent.

Hooks are a wall

The rule "never push to main" lives in CLAUDE.md. The skill /pr is easier to type than the alternative. Neither of those is enforcement.

The enforcement is a pre-push git hook.

If you (or a coding agent) run git push from a machine with our repo checked out, the hook fires before the push leaves your laptop. If the branch you are on is main or production, the hook exits 1 and prints the error message I wrote specifically for the version of me that is about to do a dumb thing. The push does not happen.

If the branch is anything else, the hook runs lint, typecheck, tests, and build locally. If any of them fail, the push does not happen.

There is a flag to skip hooks, yes. If the agent tries to use it, a separate PreToolUse hook catches the command before it runs and blocks it on protected branches. And if a push somehow lands on the remote anyway, GitHub branch protection rejects it on the server side.

I did not build all three layers on day one. I built them in the order I needed them, which is to say I built each one the first time something got past the layer before it.

There is also a SessionStart hook that runs before the agent does anything. It checks that the Node version is the one the app expects, that the environment file exists, that dependencies are up to date, that the database the session is about to touch is the development database and not production. If any of that is wrong, the session opens with a warning, and the agent is told to act on the warning before doing anything else.

None of this requires the agent to cooperate. None of it requires the human to remember.

CI is the outer wall. Six jobs, parallel, on every pull request. Lint. Typecheck. Frontend tests. Backend tests across three shards. Build. Doc drift check. If any job fails, the PR cannot merge. If the PR does not have a label, a seventh job fails. Zero warnings allowed.

This is the only layer that does not care how tired anyone is, how confused the agent is, or what quiet thing got dropped on the way through. It just says no.

Tanya has never pushed to main. She could not push to main if she tried. Neither can I. We have confirmed.

The scaffolding is the product

Here is the funny thing about all of this: none of it is new.

Linters. CI. Pre-commit hooks. Code review. Required labels. Branch protection. Engineering teams have been writing these guardrails for the humans on the team for two decades. What changed is that the same guardrails now work on the agent. And because the agent does most of the typing, they work for the non-engineer driving the agent too.

The three layers are just discipline given shape. Rules tell the agent what you want, skills make the right thing the easiest thing, hooks enforce the non-negotiables. That stack is not new. It is what engineering has been doing for twenty years, and it works.

What did change is the cost. A CLAUDE.md is an afternoon. A skill is another afternoon. A git hook is an hour. A SessionStart script is an hour. Most of them I wrote in a single week, when the alternative was cleaning up after a mistake the agent had already made twice.

The agent isn't the product, the scaffolding is. The agent is really good at working inside it without stepping on anything important.

There is one piece of scaffolding I have not been able to write.

It is the call on my calendar every few days where Tanya and I hop on a screen share and work through something hand-in-hand. We have a name for these. It is "make Tanya an engineer." Sometimes we are making her Claude Code statusline look cool. Sometimes we are picking out a new text editor and making it hers. Sometimes we are walking through how the app is put together so we can figure out how to make it even more awesome.

They are still happening. They will probably still be happening in six months. I am not trying to automate them away.

There is something about a real person on the other side of a screen share that makes the work feel survivable. A CLAUDE.md will not do that. A slash command will not do that. The hooks definitely will not do that.

That is also part of the system.

Two things I owe you

First, a callback to Guilherme on the last post. You were right that Retool is bus-factor insurance. You can also roll your own. It's called a CLAUDE.md, a pre-push hook that exits 1, and an hour-long call called "make Tanya an engineer."

Second, a correction on the opener. Tanya is not the only other person shipping code to Tiger Den. A few other folks have been committing too. I made her the hero because her two-week arc was the cleanest story. Apologies to the rest of the team for the dramatic license.

Airtable, it's been real. Tiger Den is better. Tanya is proof.

This post was reviewed and approved by Tanya before publishing. Zero AI agent skills involved.

How Do PostgreSQL Indices Work, Anyways?

Matty Stratton — Wed, 18 Mar 2026 14:35:21 +0000

You've probably created a hundred indexes in your career. Maybe a thousand. You ran EXPLAIN ANALYZE, saw "Index Scan" instead of "Seq Scan," pumped your fist, and moved on.

But do you actually know what's happening underneath? Because once you do, a lot of things about PostgreSQL performance start to make a lot more sense. And some of the pain points you've been fighting start to feel less like mysteries and more like, well, physics.

It's a tree. Obviously.

The default index type in PostgreSQL is a B-tree. You knew that. But let's talk about what that actually means for your data.

When you create an index on, say, a timestamp column, PostgreSQL builds a balanced tree structure where each node contains keys and pointers. The leaf nodes point to actual heap tuples (your rows on disk). The internal nodes just help you navigate. Think of it like a phone book. (Do people still know what phone books are? I'm aging myself.)

The key thing to understand: the index is a separate data structure from your table. It lives in its own pages on disk. When you insert a row, PostgreSQL doesn't just write your row. It also has to update every index on that table. Every. Single. One.

So if you have a table with five indexes and you're doing 50,000 inserts per second, that's not 50K write operations. That's 250K+ B-tree insertions per second, plus the heap write. Oof.

You can see exactly how much space each index is consuming with \di+ in psql:

\di+ public.*

-- Or if you want programmatic access:
SELECT indexrelid::regclass AS index_name,
       pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
       idx_scan AS times_used,
       idx_tup_read AS tuples_read
FROM   pg_stat_user_indexes
WHERE  schemaname = 'public'
ORDER  BY pg_relation_size(indexrelid) DESC;

Run that on your biggest table. If you see indexes measured in gigabytes that have idx_scan = 0, those indexes are costing you writes and giving you nothing back. They're dead weight.

Pages, not rows

Here's where it gets interesting. PostgreSQL doesn't read individual rows from disk. It reads 8KB pages. Always. Even if you only want one tiny row, you're pulling in a full 8KB page.

Your B-tree is also organized into 8KB pages. Each page holds as many index entries as it can fit. For a simple index on a bigint column, you can fit a few hundred entries per page. For a compound index on (tenant_id, event_type, created_at), you're fitting fewer because each entry is wider.

When PostgreSQL traverses your B-tree, it starts at the root page, reads it, follows a pointer to the right internal page, reads that, and eventually gets to a leaf page that tells it where your actual row lives on the heap. For a table with a million rows, that's maybe three or four page reads. For a billion rows, it might be five or six. Logarithmic scaling is your friend here.

You can see this in action with EXPLAIN (ANALYZE, BUFFERS):

EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM events WHERE created_at > now() - interval '1 hour';

-- Look for lines like:
--   Index Scan using events_created_at_idx on events
--     Buffers: shared hit=4 read=2

The shared hit count tells you how many pages came from the buffer cache. The read count tells you how many had to come from disk. If you're seeing high read values on a query you run frequently, your working set has outgrown your shared_buffers.

But. (There's always a but.)

The part nobody thinks about

Those leaf pages need to stay ordered. When you insert a new value that belongs in the middle of a page that's already full, PostgreSQL has to split that page. Page splits are expensive. They cause write amplification and can fragment your index over time.

For time-series data (timestamps always increasing), you mostly dodge this problem because new values go to the rightmost leaf. That's nice. But it creates a different problem: hot-page contention. Every concurrent insert is fighting to write to the same leaf page at the end of the tree.

And then there's the part that really gets you: MVCC overhead.

PostgreSQL's multiversion concurrency control means that even your index has to deal with tuple visibility. Index entries don't get removed immediately when a row is deleted or updated. They stick around until VACUUM cleans them up. So your index isn't just tracking live rows. It's tracking all the versions of your rows until the cleanup crew gets around to it.

For a high-churn table, your index can be significantly larger than you'd expect just from the row count. I've seen cases where the index is effectively 2-3x the "expected" size because of dead tuple bloat.

Here's how to check if bloat is eating your indexes alive:

SELECT relname,
       n_dead_tup,
       n_live_tup,
       round(n_dead_tup * 100.0 / nullif(n_live_tup + n_dead_tup, 0), 1) AS dead_pct,
       last_autovacuum
FROM   pg_stat_user_tables
WHERE  n_dead_tup > 10000
ORDER  BY n_dead_tup DESC;

If dead_pct is climbing above 10-20% and last_autovacuum was hours ago (or null), autovacuum is falling behind. That bloat isn't just wasting space. It's making every index scan touch more pages than it should.

Index-only scans (and why they're worth understanding)

There's one more behavior worth knowing about, because it changes how you think about index design.

Normally, PostgreSQL uses the index to find where a row lives on the heap, then goes and reads the actual row. That's two separate lookups: the index, then the heap.

But if every column your query needs is already in the index, PostgreSQL can skip the heap entirely. That's an index-only scan, and it's significantly faster.

-- This index covers both the WHERE clause and the SELECT list:
CREATE INDEX idx_events_covering ON events (created_at) INCLUDE (event_type, value);

-- Now this query never touches the heap:
EXPLAIN (ANALYZE, BUFFERS)
SELECT event_type, value FROM events WHERE created_at > now() - interval '1 hour';

-- Look for:
--   Index Only Scan using idx_events_covering on events
--     Heap Fetches: 0

The Heap Fetches: 0 is what you want. That means PostgreSQL answered the entire query from the index alone.

The catch: index-only scans only work well when the visibility map is up to date, which brings us right back to VACUUM. If VACUUM hasn't visited a page recently, PostgreSQL can't trust the index alone and has to check the heap anyway. So even this optimization depends on keeping autovacuum healthy.

Partial indexes (less is more)

One more tool that's underused: partial indexes. If you only query a subset of your data most of the time, you can index just that subset.

-- Instead of indexing every row:
CREATE INDEX idx_events_status ON events (status);

-- Index only the rows that matter:
CREATE INDEX idx_events_active ON events (status) WHERE status = 'active';

The partial index is smaller, faster to scan, and cheaper to maintain on writes. For high-churn tables where most queries filter to a small slice of data, this is free performance.

So why does this matter?

Understanding this stuff isn't just academic. It explains real problems you hit in production:

Why adding indexes slows down writes. Every index is another B-tree that needs to be maintained on every insert. It's not free. It's never been free. The cost just hides until you're at scale.

Why your queries get slower over time even though nothing changed. Index bloat from dead tuples. Pages that used to be tightly packed are now half-empty after splits and vacuuming. Your three-page-read query is now a six-page-read query.

Why VACUUM matters so much. It's not just reclaiming table space. It's keeping your indexes healthy. If autovacuum can't keep up, your indexes degrade. And if you're inserting fast enough, autovacuum can fall behind. That's not a bug. That's just the architecture working as designed.

Why partitioning helps (and then stops helping). Smaller partitions mean smaller indexes mean fewer tree levels. Great. But now your query planner has to evaluate all those partitions to figure out which ones to scan. And that planning cost scales linearly with partition count. You're trading one bottleneck for another.

The bigger picture

I wrote about this cycle more extensively in a piece about the PostgreSQL optimization treadmill. The short version: there's a pretty predictable progression that teams go through. Optimize indexes. Partition tables. Tune autovacuum. Scale vertically. Add read replicas. Each phase buys you a few months.

That's not a criticism of PostgreSQL. Postgres is an incredible database. But it's a general-purpose relational database, and its architecture reflects that. The heap storage model, MVCC, the query planner, B-trees. They're all designed to handle a wide range of workloads really well. The tradeoff is that for very specific access patterns (like time-series data at scale), those general-purpose design choices start working against you instead of for you.

Understanding how your indexes work is the first step to understanding when they stop being enough. And knowing when you're fighting the architecture instead of optimizing within it can save you months of whack-a-mole performance tuning.

But that's a topic for another day. For now, go run these queries on your biggest table:

-- How big are your indexes, really?
SELECT indexrelid::regclass AS index_name,
       pg_size_pretty(pg_relation_size(indexrelid)) AS size,
       idx_scan AS scans
FROM   pg_stat_user_indexes
WHERE  relname = 'your_table_here'
ORDER  BY pg_relation_size(indexrelid) DESC;

-- Are any of them unused?
SELECT indexrelid::regclass AS index_name,
       idx_scan
FROM   pg_stat_user_indexes
WHERE  idx_scan = 0
  AND  schemaname = 'public'
ORDER  BY pg_relation_size(indexrelid) DESC;

You might be surprised.

Coding Agents Are Actually Good at This One Thing

Matty Stratton — Sun, 01 Mar 2026 20:31:28 +0000

The discourse around AI coding tools tends to collapse into two camps: people who think they're going to replace developers, and people dunking on "vibe coding" demos that fall apart the moment you look at them sideways.

Both camps are mostly arguing about the wrong thing.

I've been using coding agents heavily for the past few months, and the use case where they've actually changed how I work isn't production applications or greenfield SaaS ideas. It's internal tooling. And that distinction matters more than people are giving it credit for.

The Airtable Problem

For years, I built internal tools the way most of us did: I found something close enough and made it work. Airtable was great for this. I built conference talk trackers, content inventories, planning dashboards... all kinds of things. The spreadsheet-meets-database model was genuinely useful, and for a while, it was the right call.

But you're always fighting two things with tools like Airtable or Notion or even Asana when you're bending them to a purpose they weren't built for. First, you fight the constraints of the tool itself: the data model it has, the views it supports, the automations it allows. Second, you fight the cost and friction of giving your whole team access to yet another SaaS platform.

At some point the juice stops being worth the squeeze. You're not building what you actually need, you're building the closest approximation that fits inside someone else's product.

Just Build the Thing

What coding agents have unlocked for me is the ability to just build the thing.

The project I've been heads-down on is called Tiger Den: an internal content management system for our Marketing team at Tiger Data. It's a Next.js app, Drizzle ORM, tRPC, Postgres (running on Tiger Data, natch). A real web app with a real database, exactly structured for how we actually work.

Tiger Den manages our content library, tracks blog posts and videos, stores voice profiles for different authors so we can make sure our content matches our voices, generates UTM links, and surfaces the right content for the right workflow. It's not a product. It's not trying to be. It's a tool that fits our team's exact needs because we built it for our team's exact needs.

A few folks on the team are starting to use it. Workflows that used to involve a bunch of spreadsheet wrangling and web search gymnastics are getting simpler. It's not fully baked (it's somewhere between "mostly works for me" and "the team is starting to play with it") but it's already more useful than what it replaced (a combination of "nothing" plus "not very updated spreadsheet"), and I've been iterating on it continuously.

That iteration speed is the point.

Why Internal Tooling Specifically

The reason coding agents shine here, and why I keep coming back to this use case, is the risk profile.

When you're building a public-facing application, you have to worry about edge cases at scale, security hardening, performance under load, what happens when a user does something unexpected, what happens when a thousand users do something unexpected. The cost of getting it wrong is high.

Internal tools have a completely different calculus. The user population is small and known. The stakes for any individual bug are low. You can ship something that's 80% right and fix the other 20% next week. You can move fast and it's actually fine.

This is the Microsoft Access model, honestly. In the 90s and early 2000s, people built remarkably functional internal tools in Access (forms, reports, relational data, real logic) because the barrier was low enough that you could actually do it. Then the web happened, the complexity went way up, and that era of "just build the thing" basically ended for most people.

Coding agents are bringing it back. The barrier is low again. You can describe what you want, iterate in a tight loop, and end up with something that actually fits your use case instead of something that almost fits someone else's template.

What About Retool?

When I posted about this, someone brought up Retool — fair question. Isn't that exactly what Retool is for?

Maybe. But my reaction was: isn't that just trading one set of constraints for another? Now I'm stuck on how Retool thinks about the world instead of how Airtable thinks about the world. I haven't dug deep into Retool, so I'm not going to trash it, but the pattern is the same: you're building inside someone else's model of what your tool should be.

The thing I actually want is to build the thing I want. That's what "just use Next.js and a database" gives me.

Some Honest Caveats

I want to be careful not to oversell this, because the context matters a lot.

I'm a systems guy. Infrastructure, security, DevOps, that's my background. I could build Tiger Den without a coding agent; it would just take a lot longer because I'm coming at software development somewhat sideways. The agent collapses that time gap significantly. But I'm still making real architectural decisions, reviewing what gets generated, and understanding the codebase well enough to maintain it. This isn't "describe what you want and walk away."

Someone also asked about maintenance (a reasonable concern!). My answer: for Tiger Den specifically, I'm only writing to my own database. I'm not doing write operations against external systems, I'm not touching production data, and the blast radius of any given bug is small. That's a deliberate choice, and it's part of why internal tooling is the right framing. If I were building something that talked to our customers' data or integrated deeply with critical external systems, I'd be a lot more careful.

The low-stakes calculus stops applying the moment you have real users, real consequences for downtime, or data you can't afford to mess up. Keep that boundary clear and this approach works really well. Blur it and you're asking for trouble.

But for "my team needs a thing and the existing tools don't quite fit"? This is legitimately transformative. I've wanted to be able to build internal tools this easily for a long time. Now I can.

Airtable, it's been real. Tiger Den is better.

Product 101: Your Secret Weapon for Understanding the Business

Matty Stratton — Tue, 04 Nov 2025 14:58:55 +0000

This is Part 5 of my 7-part series on business literacy for DevRel. Start with Part 1 if you missed it.

We've covered sales, marketing, and finance. But there's one group we haven't talked about yet - and they might be your most valuable partnership in the entire company: Product.

Not because product managers are inherently better than anyone else (though the good ones are pretty great). But because strategic product leaders sit at the intersection of everything. They see the business from a unique vantage point that can be incredibly valuable to DevRel.

A good product partner is worth their weight in gold. They're your early warning system, your business intelligence source, and your reality check all rolled into one.

What Product Actually Does

At the most basic level, product management is about figuring out what to build, why to build it, and making sure it actually gets built.

But that simple description hides a ton of complexity:

Product managers (PMs) are responsible for:

Deciding what features/capabilities to prioritize
Understanding user needs and market opportunities
Working with engineering to build the right things
Collaborating with go-to-market teams (sales, marketing) to position and launch features
Measuring whether what they built is actually working
Saying "no" to a lot of things (this is actually most of the job)

Product sits at the center of a bunch of competing pressures:

Sales wants features that will close deals
Marketing wants things that will generate buzz
Engineering wants to build technically interesting things
Finance wants efficient use of resources
Customers want their specific problems solved
Executives want the product to support business strategy

The PM's job is to synthesize all of this and make decisions about what the product should become.

Meet the Product Team: Roles You Need to Know

Chief Product Officer (CPO) / VP of Product: Sets the overall product vision and strategy. They're thinking about where the product needs to be in 2-3 years, not just next quarter. They usually report directly to the CEO.

Director of Product / Senior PM: Usually owns a major product area or domain. They're thinking strategically about their area while managing other PMs.

Product Manager (PM): Owns a specific product or feature area. They work day-to-day with engineering teams to ship features. This is who you'll probably work with most.

Technical Product Manager (TPM): Like a PM but more technical. Often owns platform, API, or developer-facing products. If you work at a developer tools company, TPMs are your people.

Product Marketing Manager (PMM): We talked about these folks in the marketing post, but they sit between product and marketing. They take what product builds and figure out how to position and message it.

Product Operations / Product Ops: Help PMs be more effective by managing tools, processes, and data. They're the behind-the-scenes folks making product teams run smoothly.

How Product Thinks About the World

Product managers live in a few key frameworks. Understanding these helps you speak their language:

The Product Roadmap

This is the plan for what gets built when. Roadmaps are usually organized by quarters or releases, and they're always wrong (because priorities change).

Roadmaps are political documents as much as planning documents. What makes it onto the roadmap and what doesn't tells you a lot about what the business values.

User Stories and Jobs to Be Done

PMs think about user needs in terms of "user stories" (as a [role], I want to [do something] so that [outcome]) or "jobs to be done" (when [situation], I want to [motivation], so I can [expected outcome]).

This is useful for DevRel because it's how you can frame developer feedback. Instead of "developers want feature X," try "when developers are trying to debug production issues, they want observability into what the system is doing, so they can identify root causes faster."

Prioritization Frameworks

PMs are always prioritizing. Common frameworks:

RICE: Reach, Impact, Confidence, Effort
Value vs. Effort: Classic 2x2 matrix
Kano Model: Basic needs vs. performance needs vs. delighters

Understanding how your product team prioritizes helps you frame feedback effectively.

Success Metrics

Good PMs are all about metrics:

Activation: Did users do the key action that shows they "get" the product?
Engagement: Are users coming back? How often?
Retention: Are users sticking around over time?
Feature adoption: Are users actually using the new thing we built?
Time to value: How quickly can users get value from the product?

Notice how some of these overlap with PLG metrics? That's not an accident.

Why Product Matters So Much to DevRel

Here's where it gets interesting. Product is uniquely positioned to give you intelligence about the business that you can't get anywhere else.

They See Across Functions

A strategic PM talks to:

Sales (what's blocking deals?)
Marketing (what's resonating in the market?)
Customer success (what are customers struggling with?)
Engineering (what's technically feasible?)
Finance (what can we afford?)
Executives (what's the strategy?)

They're synthesizing information from everywhere. If you have a good relationship with product leadership, they can give you context on what's really happening across the business that you'd never get from any single function.

They Know What's Coming

Product knows what's on the roadmap before it's public. This is incredibly valuable for DevRel:

You can prep content in advance
You can understand strategic direction
You can give early feedback on how developers will react
You can plan your activities around major releases

They Need What You Have

As a devrel, you're sitting on a goldmine of information that product desperately needs:

What developers are actually struggling with
What features developers are asking for (and why)
How developers talk about problems in their own language
What the competition is doing (you see it at conferences and in communities)
Which parts of your product confuse people

This creates natural reciprocity. You help them, they help you.

They Fight Similar Battles

Good PMs face the same challenge you do: they have to translate between technical reality and business objectives. They have to advocate for what's right while acknowledging business constraints.

You're natural allies.

The Product/DevRel Partnership

When done right, the Product/DevRel partnership is incredibly powerful:

DevRel provides Product:

Raw, unfiltered user feedback from communities
Market intelligence from conferences and events
Early signals about what developers care about
Reality checks on how features will be received
Developer perspective on product decisions

Product provides DevRel:

Early access to roadmap and upcoming features
Context on why decisions were made
Understanding of strategic priorities
Cross-functional intelligence
Air cover when you need to push back on requests

The Feedback Loop

One of DevRel's most valuable contributions is being a structured feedback channel from developers to product. But this only works if you do it right:

Bad feedback: "Developers want dark mode"

Good feedback: "I'm seeing consistent requests for dark mode from developers who code at night. The specific pain point is eye strain during long coding sessions. This came up in 15+ community conversations last month, and competitors X and Y both shipped this recently."

Bad feedback: "This new feature is confusing"

Good feedback: "In office hours, 3 out of 5 developers got stuck at the same step in the new onboarding flow. The confusion is around [specific thing]. Here's a recording of where they got stuck."

Strategic product leaders eat this stuff up because it's specific, actionable, and helps them make better decisions.

Not All PMs Are Created Equal

That said, not every PM is strategic. Some are just feature factories, cranking out roadmap items without understanding the broader context.

A comment that inspired this post mentioned this perfectly: not every product leader can "get their heads out of the sands of features/roadmap, nor are they all observant of business value themselves."

Look for PMs who:

Understand the business model, not just the feature list
Can articulate why something is being built, not just what
Talk to customers and users regularly
Have opinions about strategy, not just execution
Are curious about the market and competition
Actually understand the technical implications of their decisions

These are the ones worth partnering closely with. The others... well, you can still work with them, but don't expect the strategic partnership.

How Product Decisions Happen (And Where You Fit In)

Understanding how product decisions get made helps you influence them:

Input gathering: PMs collect input from sales, customers, community, market research, executives, etc.

Prioritization: PMs use frameworks to decide what's most important

Roadmap planning: Decisions get formalized into "we're building X in Q2"

Execution: Engineering builds it

Launch: Product goes to market with help from marketing, sales, and (hopefully) DevRel

Measurement: Did it work?

DevRel can influence at almost every stage:

Input: Share developer feedback
Prioritization: Provide market context
Roadmap: React to plans, suggest adjustments
Execution: Give technical feedback during development
Launch: Create content, drive awareness
Measurement: Share qualitative feedback on how it's landing

But you have to be in the conversation to have influence. Which means building relationships.

The DevRel Seat at the Product Table

Some DevRel teams are deeply integrated with product. Others are completely disconnected. If you're in the latter camp, here's how to change that:

Start small: Ask to sit in on a product planning meeting as an observer
Provide value first: Share useful feedback before asking for anything
Speak their language: Frame things in terms of user problems and business impact
Be consistent: Show up regularly with valuable input
Don't be precious: Accept that you won't always get what you want
Understand constraints: Product is making trade-offs; understand what they are

Regular Touchpoints That Work

Consider establishing:

Monthly sync with product leadership: Share what you're hearing, get context on roadmap
Feedback review sessions: Present synthesized developer feedback quarterly
Early access to betas: Get hands-on with features before launch
Launch planning collaboration: Work together on go-to-market for major features
Roadmap input sessions: Provide perspective on upcoming priorities

Product Gives You Business Intelligence

Here's something nobody talks about: a good product partner can be your best source of business intelligence.

They'll tell you things like:

"Sales is really struggling in the enterprise segment right now"
"We're shifting strategy toward [market] next year"
"The exec team is worried about [competitive threat]"
"Marketing's campaigns aren't converting well"
"There might be budget cuts coming"

Why do they know this? Because they're in all the meetings. They see the cross-functional dynamics. They hear what's really going on.

And if they trust you, they'll share it. This is incredibly valuable for planning your DevRel strategy and seeing what's coming.

Essential Product Terminology

Let me give you the vocabulary:

MVP (Minimum Viable Product): The smallest version of something that delivers value. Often used as an excuse to ship incomplete things, but the concept is sound.

Product-Market Fit: The magical moment when you've built something that a market actually wants. Most products never achieve this.

Feature parity: Having the same features as competitors. Often overvalued by sales, undervalued by product.

Technical debt: The accumulated cost of quick-and-dirty technical decisions. Always more than you think.

Dogfooding: Using your own product internally. Good PMs do this religiously.

Beta / Alpha: Early versions for testing. Alpha is usually internal, beta is usually external but limited.

GA (General Availability): The feature is fully launched and available to everyone.

Sunset / Deprecation: Retiring a feature or product. Always painful, usually necessary.

OKRs (Objectives and Key Results): How many product teams set goals. Objectives are qualitative, key results are measurable.

What This Means For Your Work

Understanding product doesn't mean becoming a PM. It means:

You can provide product with valuable, actionable feedback
You can anticipate what's coming and plan accordingly
You can understand why certain decisions are made (even when you disagree)
You can be a strategic partner instead of just a feedback conduit
You have access to cross-functional intelligence that helps you navigate the business

Product is your window into how the whole business is working - the headwinds, the tailwinds, the tensions, the priorities. Use it.

Finding Your Product Partner

Not sure who to connect with in product? Start here:

Identify the PM who owns your developer-facing products (API, SDK, CLI, etc.)
Reach out with value: "Hey, I'm hearing a lot of feedback about [thing]. Want to chat?"
Be low-maintenance: Respect their time, be organized, come prepared
Look for strategic thinkers: Find the PMs who see the bigger picture
Build the relationship over time: This is a long game

And if you find a great product partner? Hold onto them. They're rare and incredibly valuable.

Next up: we'll talk about Product-Led Growth and how it changes everything about the relationship between product, DevRel, and go-to-market. Spoiler: in PLG companies, product and DevRel become deeply intertwined.

Questions about working with product? War stories about great (or terrible) product partnerships? Let's hear them in the comments!

Previously: Part 4: Finance 101

Next up: Product-Led Growth

Putting It All Together: Speaking Business as a DevRel Professional

Matty Stratton — Tue, 28 Oct 2025 18:54:34 +0000

This is Part 7 of my 7-part series on business literacy for DevRel. Start with Part 1 if you missed it.

We've covered a lot of ground in this series. Sales pipelines and forecast accuracy. Marketing funnels and MQLs. P&Ls and CapEx vs OpEx. Product-Led Growth and how it changes the game for developer tools companies. If your brain feels a little full right now, that's normal. This is a lot of new vocabulary and new ways of thinking.

But you now have the foundation. You understand the basics of how the key parts of your business operate, what they care about, and what language they speak. You understand how modern go-to-market models work and where DevRel fits in.

Now let's talk about what you actually do with all this knowledge.

Where DevRel Sits in the Business Landscape

If you think about your company as an ecosystem, DevRel occupies a unique position. You're not sales, but you influence deals. You're not marketing, but you create awareness and demand. You're not product, but you deeply understand user needs. You're not support, but you help developers be successful.

I often say "DevRel rhymes with lots of different parts of the business"

You're the bridge. You're the translator. You're uniquely positioned to connect the technical world of developers with the commercial world of business.

And that's actually a superpower, not a weakness. The question is, are you using it?

The DevRel Translation Guide

Let's get practical. Here's how you translate common DevRel activities into language that resonates with different stakeholders:

Example 1: Conference Talks

What you do: Give a technical talk at a conference about solving a real problem using your technology

How different stakeholders hear it:

To Sales: "This is TOFU content that builds awareness and credibility in a target market. Prospects who attend or watch this talk are more likely to trust us when we're in their consideration set."

To Marketing: "This creates thought leadership content at the top of the funnel, reaching developers in our target persona. The recorded talk becomes an asset we can promote for months."

To Finance: "For a $5K investment (travel, event costs), we reach 200 in-person developers and potentially 10K+ via the recorded talk. Compared to paid advertising costs of $50-100 per qualified lead, this is highly efficient awareness generation."

To Your CEO: "This positions our company as a technical leader in [space], increases brand awareness with our target audience, and creates trust that accelerates the sales cycle."

Example 2: Office Hours Program

What you do: Run weekly office hours where developers can get help with technical challenges

How different stakeholders hear it:

To Sales: "This is MOFU activity that helps prospects overcome technical blockers that might prevent deals from closing. Sales can invite prospects to office hours as a value-add during the evaluation phase."

To Marketing: "This creates ongoing touchpoints with developers in the consideration phase, moving them down the funnel. It also generates insights about common pain points we can address in our content."

To Finance: "This program costs approximately $X per quarter (staff time) and supports Y developers, reducing the load on our paid support team (saving $Z) while accelerating deal velocity."

To Product: "This is a direct line to user feedback. We're hearing real problems from real users, which informs our product roadmap and helps prioritize features."

Example 3: Documentation Improvements

What you do: Rewrite documentation to make it clearer and more accessible for developers

How different stakeholders hear it:

To Sales: "Better docs reduce technical objections during the sales cycle. When prospects can self-serve and get quick answers, it reduces friction in the buying process."

To Marketing: "Great docs are a conversion tool. When someone is evaluating our product, comprehensive docs signal quality and reduce perceived risk."

To Finance: "Improved docs reduce support ticket volume by X%, which translates to $Y in reduced support costs. It also improves trial-to-paid conversion, impacting revenue."

To Product: "Quality documentation improves user experience and product adoption, which reduces churn and improves LTV."

Example 4: Community Building

What you do: Build and nurture an active community where developers help each other

How different stakeholders hear it:

To Sales: "An active community is social proof. When prospects see thousands of engaged developers, it reduces perceived risk and speeds up the sales cycle."

To Marketing: "Community creates network effects that reduce our CAC over time. Developers in the community become advocates who bring in new users organically."

To Finance: "The community provides peer-to-peer support that would otherwise require paid support resources. If 70% of questions are answered by community members, that's saving us $X in support costs annually."

To Your CEO: "Our community is a competitive moat. It's relationship capital that competitors can't easily replicate, and it creates switching costs that improve retention."

Having Better Conversations With Stakeholders

The key to using your business literacy isn't just knowing the vocabulary. It's understanding what different stakeholders care about and framing your work in those terms.

With Sales

Talk about: pipeline influence, deal velocity, technical credibility, competitive positioning, removing buying blockers

Example: "I'd like to pilot a program where DevRel joins strategic deals for technical deep dives. Based on what I've seen, this could reduce time-to-close by 2-3 weeks by addressing technical concerns earlier in the cycle. Want to try this with three opportunities next quarter and measure the impact?"

With Marketing

Talk about: funnel stages, campaign support, content performance, lead quality, brand awareness

Example: "I noticed the marketing team is planning a campaign around [topic]. DevRel can support this by creating technical deep-dive content that serves the MOFU stage. We'll own the technical accuracy and authentic voice, which should improve conversion from awareness to consideration."

With Finance

Talk about: budget allocation, ROI, cost efficiency, strategic investment, measurable outcomes

Example: "I'm requesting $30K for three conference sponsorships next quarter. Based on last year's data, this typically generates 150 qualified conversations, with 10-15 entering our pipeline. At our average deal size, if just two deals close, that's $200K in revenue from a $30K investment."

With Executives

Talk about: business objectives, market position, competitive advantage, growth levers, strategic priorities

Example: "Our community strategy supports three key company objectives: it reduces CAC through organic growth, it creates customer stickiness that improves retention, and it provides product insights that help us build what developers actually need. This quarter we'll focus on [specific initiative] to accelerate growth in [target segment]."

Common Pitfalls to Avoid

As you develop your business literacy and start speaking this language, watch out for these traps:

Over-rotating to business speak: Don't become so focused on business outcomes that you lose sight of serving developers. If developers don't genuinely benefit from what you're doing, it's not sustainable DevRel work.

Claiming direct attribution when it's influence: Be honest about what you can and can't directly attribute to DevRel. Influence is still valuable, but don't claim you "closed the deal" when you participated in one discovery call.

Using business literacy to justify work that doesn't serve developers: Business literacy should help you advocate for developer-serving work, not rationalize doing things that only benefit the business.

Becoming a "mini-marketer": You're not marketing. You can use marketing language to communicate, but don't let that change what you actually do or how you do it.

Overpromising to get budget: It's tempting to make big claims to secure resources, but if you can't deliver, you damage your credibility for future asks.

Business Literacy ≠ Selling Out

Let's address this head-on one more time: learning to speak business language doesn't mean you're selling out.

You're still serving developers first. You're still advocating for their needs. You're still building authentic relationships and creating genuine value.

What you're doing is making sure the people who control resources understand why that work matters to the business. You're ensuring that the work you believe in gets funded. You're protecting your team and your programs by being able to articulate their value.

The alternative - being "too pure" to speak business language - often ends with your team getting cut and your programs getting defunded. And then who does that serve?

Some of the most authentic, developer-focused DevRel professionals I know are also fluent in business language. They use that fluency to advocate more effectively for developers. They're bilingual, not sell-outs.

Now You're Ready for the Next Level

With the foundation of business literacy, you can now tackle the more advanced challenges:

Developing meaningful DevRel metrics that map to business objectives
Building attribution models that give you credit for influence without overclaiming
Creating business cases for new DevRel initiatives
Demonstrating ROI in ways that are credible to finance teams
Advocating for budget and headcount using compelling business logic

These advanced topics deserve their own deep dives (and there are good resources out there on these topics). But without the foundation we've built in this series, those advanced topics don't make sense. You'd be trying to build a measurement framework without understanding what matters to the business. You'd be creating attribution models without understanding how marketing thinks about attribution. You'd be requesting budget without speaking the language of finance.

Work as Imagined vs Work as Done

There's this concept from safety science: "work as imagined" vs "work as done." Work as imagined is how things are supposed to work in theory. Work as done is the messy reality of how things actually work.

A lot of the DevRel discourse happens in "work as imagined" territory. In theory, we should just be able to show our impact through beautiful metrics. In theory, executives should just trust that DevRel is valuable. In theory, we shouldn't have to speak business language because our work should speak for itself.

But that's not work as done. In reality, we operate in companies with finite resources, competing priorities, and stakeholders who think in different frameworks. In reality, business literacy is table stakes for being taken seriously.

Focus on work as done. Learn the language. Have the conversations. Bridge the gaps.

Your Network Is Vast: DevRel as BizDev

Here's one more thing to consider: your network is one of your most valuable assets, both personally and for your company.

You know people at other companies. You have relationships in the developer community. You're connected to potential partners, customers, and advocates.

This makes you valuable in ways that go beyond traditional DevRel metrics. Want to explore a partnership with another company? You probably know someone there. Need to get into a strategic account? Your network can probably help with an introduction.

I'm not saying you should become a business development person. But I am saying that leveraging your network thoughtfully (and with appropriate boundaries) is another way DevRel creates business value.

Show Value But Set Boundaries

As you become more business-literate and better at articulating your value, you'll likely get more requests. Sales will want you on more calls. Marketing will want you to support more campaigns. Executives will want you to do more things that "require less imagination to show value."

This is where boundaries matter:

"I'll call in a favor from my network - once."
"I'll share company news on social media, but in my own words and only if I genuinely think it's interesting."
"I'll meet with prospects for technical discussions, but I won't do sales demos or pitch."
"I'll write about new features after I've used them, and I'll share my honest impression."

Your boundaries might be different. The key is being intentional about what you will and won't do. And remember: boundaries can be flexible and situational. But they should be conscious choices, not things that happen to you.

Final Thoughts

Business literacy is power. It's the power to advocate effectively. The power to protect your team. The power to fund the programs that serve developers. The power to have a seat at the strategic table.

You don't need to become a finance expert or a sales leader or a marketing strategist. But you need to understand enough about how these functions work to translate between their world and yours.

The cognitive dissonance a lot of DevRel folks feel - between "DevRel is good and pure and unsullied by capitalism" and "the company has to generate revenue and DevRel is part of that" - that dissonance is real. But it's also false tension.

You can serve developers AND contribute to business success. You can be authentic AND speak business language. You can maintain your integrity AND work effectively with sales and marketing.

In fact, you kind of have to. Because if you're not connected in a measurable way to either building the thing or selling the thing, it's going to be really hard to stick around for the encore.

Get over yourself. Learn the language. Bridge the gap. And go be awesome...together with the rest of your company.

Resources for Continued Learning

Want to deepen your business literacy? Here are some places to start:

Take a basic business finance course (lots of free options on Coursera, edX)
Read your company's financial statements (if public) to understand how they talk about the business
Ask to shadow someone in sales/marketing/finance for a day
Read business books focused on SaaS/tech companies (I recommend "Crossing the Chasm" by Geoffrey Moore as a starting point)
Follow finance and business leaders on social media to absorb how they think

And most importantly: ask questions. The folks in sales, marketing, and finance usually love explaining their world to people who are genuinely curious.

Jeremy Meiss has written some great next step posts for you to consider:

What's Next For You?

So here's my question for you: what's one thing you're going to do differently based on this series?

Maybe you're going to schedule coffee with someone from your sales team to understand their pipeline better. Maybe you're going to reframe how you talk about your work in your next stakeholder meeting. Maybe you're going to actually read through your company's budget process documentation (I know, thrilling stuff).

Whatever it is, don't let this just be information you consumed. Make it actionable.

If you want to continue this conversation, I'm always available on Mastodon, LinkedIn, and BlueSky. Share your experiences, your questions, your disagreements. This is work in progress for all of us.

Thanks for sticking with this series. Now go forth and speak business fluently while never forgetting who you're really here to serve: the developers.

Build the thing. Sell the thing. But most importantly, make developers' lives better. That's the job.

Product-Led Growth and What It Means for DevRel

Matty Stratton — Tue, 28 Oct 2025 18:54:05 +0000

This is Part 5 of my 7-part series on business literacy for DevRel. Start with Part 1 if you missed it.

We've covered sales, marketing, and finance - the three core business functions you need to understand. But there's one more concept that ties everything together, and it's especially critical if you work at a developer tools company or any company with a self-serve product: Product-Led Growth (PLG).

If you've been around tech for the past five years, you've definitely heard this term thrown around. And if you're like most people, you might have a vague sense that it means "the product sells itself" but aren't totally clear on what that actually means or how DevRel fits in.

This is the missing piece. Because understanding PLG fundamentally changes how you think about the relationship between DevRel, sales, marketing, and product.

What Product-Led Growth Actually Means

Product-Led Growth is a go-to-market strategy where the product itself is the primary driver of customer acquisition, expansion, and retention. Instead of relying heavily on sales teams to convince people to buy, the product experience convinces them.

Think about how you adopted tools like Slack, Figma, or GitHub. You probably didn't talk to a sales rep first. You or someone on your team just started using it. The product was good enough that you kept using it. Eventually you needed more features or more seats, so you paid for it. Maybe your whole company ended up adopting it, even though it started with one team.

That's PLG in action.

In a traditional sales-led model, the sequence is: Sales → Trial → Adoption → Payment

In a product-led model, it's: Product → Adoption → Payment → Sales (maybe)

Why PLG Matters (Especially For Developer Tools)

Developers hate being sold to. You know this. I know this. We all know this.

Developers want to:

Try things before buying
Evaluate on their own terms, not on a sales rep's calendar
Get hands-on experience without talking to anyone
Make technical decisions based on actual experience, not marketing claims

This is why so many successful developer tools companies use PLG. It aligns with how developers actually want to evaluate and adopt tools.

Companies like Stripe, Twilio, HashiCorp, MongoDB, and countless others have proven that PLG works incredibly well for developer products. And it's a model where DevRel can be absolutely critical to success.

The PLG Funnel (It's Different)

In a traditional sales-led company, the funnel looks like:

Awareness → Lead → MQL → SQL → Opportunity → Customer

In a PLG company, it's more like:

Awareness → Sign-up → Activation → Active Usage → Power User → Paying Customer → Expansion

Let's break down these stages:

Sign-up: User creates an account. This is easy - usually just an email address. The barrier is intentionally low.

Activation: User completes the critical actions that demonstrate they "get" the product. For GitHub, this might be creating their first repository. For Stripe, it's making a test API call. This is often called the "aha moment."

Active Usage: User is regularly using the product and getting value from it. They've integrated it into their workflow.

Power User: User is deeply engaged, using advanced features, bringing in teammates. They're getting significant value.

Paying Customer: User hits some limit (features, usage, seats) and converts to paid. Critically, this often happens without ever talking to sales.

Expansion: Customer uses more features, adds more users, upgrades tiers. Again, often self-serve.

Where DevRel Fits in PLG

Here's where it gets interesting for you: DevRel is absolutely critical at almost every stage of the PLG funnel.

Awareness Stage

This is classic DevRel territory. Your conference talks, blog posts, podcasts, social media presence - all of this drives awareness. The difference in PLG is that you're not trying to generate leads for sales; you're trying to get people to sign up and try the product.

Your call-to-action isn't "talk to sales" - it's "try it yourself right now."

Sign-up to Activation (The Critical Gap)

This is where a LOT of PLG companies struggle. People sign up, poke around, don't understand the value, and leave. The activation rate might be 20-30%.

DevRel can massively impact this through:

Great documentation that gets people to their "aha moment" fast
Quick-start guides and tutorials
Sample projects and templates
Video walkthroughs
Office hours where people can get unstuck

You're essentially reducing time-to-value. The faster someone gets value, the more likely they activate.

Active Usage to Power User

Once someone is using the product, DevRel keeps them engaged and helps them go deeper:

Advanced tutorials and use cases
Community where they can learn from peers
Content about best practices and patterns
Events and workshops that teach advanced features

You're helping users get more value from the product, which increases stickiness.

Power User to Paying Customer

This conversion often happens naturally when users hit limits, but DevRel can influence it:

Case studies showing how others use paid features
Content that highlights the value of premium capabilities
Community members sharing their experiences with paid tiers

You're not selling, but you're helping people understand when and why to upgrade.

Paying Customer to Expansion

DevRel helps customers expand their usage:

Training on enterprise features
Best practices for scaling
Community connections that show what's possible
Advocacy that keeps them engaged and excited

PLG Metrics That Matter to DevRel

In a PLG company, the metrics you care about shift a bit:

Sign-ups: How many people are creating accounts? Your awareness activities drive this.

Activation Rate: What percentage of sign-ups reach the "aha moment"? Your onboarding content affects this.

Time to Value: How quickly do users get value? Your documentation and tutorials impact this.

Product Qualified Leads (PQLs): Users who have demonstrated high engagement and fit the profile for conversion to paid. This is PLG's version of an MQL.

Free-to-Paid Conversion Rate: What percentage of free users convert to paid? Your content about premium features influences this.

Net Revenue Retention (NRR): Are existing customers expanding their usage? Your community and advanced content affect this.

Community Engagement: Active community members are more likely to convert and expand. Your community building directly impacts this.

The beautiful thing about PLG is that DevRel activities have clearer, more direct metrics. You can often see: this piece of content led to X sign-ups, Y of whom activated, and Z of whom converted to paid.

The Sales-Assist Model (PLG + Sales)

Here's where it gets nuanced: most PLG companies still have sales teams. They just work differently.

In a PLG company, sales typically does one of two things:

1. Sales-Assist for Expansion: Free users become paid users on their own, but when they want to expand significantly (more seats, enterprise features), sales gets involved to help close bigger deals.

2. Land-and-Expand: Sales might not touch small deals at all, but once an account reaches a certain size or shows certain behaviors, sales reaches out to help them expand.

This is sometimes called "Product-Led Sales" - sales that's triggered by product usage signals, not traditional lead gen.

What This Means for DevRel in a PLG Company

If you work at a PLG company (or your company is moving toward PLG), your role is even more critical:

You're a growth driver, not just brand building: In traditional sales-led companies, DevRel is often seen as brand/awareness. In PLG companies, DevRel directly impacts the metrics that matter - sign-ups, activation, and conversion.

Documentation and onboarding are strategic: These aren't afterthoughts; they're core to the business model. Investing in great docs isn't nice-to-have; it's mission-critical.

Community is a growth engine: Active community members are more likely to convert, expand, and bring in new users. Community building isn't just feel-good work; it's a competitive advantage.

Your content directly impacts the funnel: That tutorial you wrote? It's not just TOFU content - it might be what gets someone from sign-up to activation. That's directly impacting conversion.

You work more closely with product: In PLG, the line between product and go-to-market blurs. You need to work closely with product teams to ensure the product experience supports the PLG motion.

PLG Changes the Business Literacy Conversation

Remember all that stuff we talked about in earlier posts about explaining your value? In PLG companies, it's often easier because the connection is more direct:

To Sales: "DevRel is filling the top of the funnel and helping users get to PQL status faster, which gives you higher-quality accounts to work with."

To Marketing: "DevRel is driving sign-ups and activation, which are our primary growth metrics. We're also reducing time-to-value, which improves our conversion rates."

To Finance: "DevRel investments directly correlate with sign-up growth and activation improvements. Here's the data showing how tutorial usage maps to activation rate."

To Product: "DevRel is hearing user feedback at scale and seeing where people get stuck in the onboarding flow. This intelligence helps you improve the product experience."

The Dark Side of PLG (That Nobody Talks About)

PLG isn't magic. It has challenges:

The Free User Problem: In PLG, you have tons of free users who may never convert. Supporting them costs money. DevRel needs to help free users get enough value to convert, without providing so much support that it's not sustainable.

Activation is Hard: Most people who sign up for a product never activate. This can be demoralizing if your sign-up numbers look great but activation is terrible. DevRel can help, but can't fix a fundamentally confusing product.

Self-Serve Isn't Always Better: Some products are complex enough that they need human help. Forcing a pure PLG motion when the product isn't ready for it doesn't work.

Support Burden: When you have thousands of free users, the support and community management burden can be enormous. DevRel often ends up carrying this, and it needs resources.

Traditional Sales-Led vs PLG: Not Either/Or

Here's the thing: most companies aren't purely PLG or purely sales-led. They're hybrid.

You might have a free tier and self-serve paid tier (PLG), but also have a sales team for enterprise deals (sales-led). This is really common.

Or you might start PLG for small teams, but sales gets involved when an account grows to a certain size.

Understanding both models - and how they work together - makes you more effective. You can support the PLG motion for individual developers and small teams while also supporting sales when they're working with larger accounts.

How to Think About PLG as a DevRel Professional

If your company is PLG or moving toward PLG:

Embrace it: PLG aligns really well with DevRel values. Letting the product speak for itself, empowering users to evaluate on their own terms, removing barriers - this is all good stuff.

Get closer to product data: Work with your product team to understand metrics like activation rate, time-to-value, and conversion funnel. Ask for access to dashboards. Understand what users are actually doing in the product.

Focus on onboarding: The period between sign-up and activation is critical. Invest heavily in making this smooth.

Build feedback loops: PLG gives you tons of data about what's working and what's not. Use it to improve docs, content, and even influence product decisions.

Think about the full journey: Don't just focus on awareness. Think about how your work impacts every stage from sign-up to expansion.

The Bottom Line

Product-Led Growth isn't a replacement for sales or marketing. It's a different go-to-market motion that changes how everything works, including DevRel.

In PLG companies, DevRel isn't just "nice to have" - it's essential infrastructure. Great docs aren't a nice-to-have; they're what makes the PLG motion work. Active community isn't just engagement; it's what drives retention and expansion.

Understanding PLG helps you:

Position your work more strategically
Focus on the right activities
Measure impact more directly
Collaborate better with product, marketing, and sales
Advocate for resources more effectively

If you're at a PLG company and you haven't been thinking about your work through this lens, start now. And if you're at a traditional sales-led company but serve developers, consider whether some PLG principles could make your work more effective.

Either way, understanding PLG is part of business literacy for modern DevRel. Add it to your toolkit.

Want to Go Deeper?

Some resources on PLG:

Product-Led Growth by Wes Bush (book)
OpenView's PLG resources (they coined the term)
Is Product Led Growth the DevOps of DevRel? (Daniel Bryant's talk at DevRelCon 2022)

Next up, we're bringing it all together in the final post - how to actually use this business literacy in your day-to-day DevRel work. How to translate what you do into language that resonates with stakeholders. How to speak business without losing your soul.

As always, comments are open below if you want to discuss, debate, or share your PLG experiences.

Previously: Part 5: Product 101

Next up: Wrapping it all up

Finance 101: Budgets, P&Ls, and the Language of Money

Matty Stratton — Tue, 28 Oct 2025 18:53:35 +0000

This is Part 4 of my 7-part series on business literacy for DevRel. Start with Part 1 if you missed it.

Time for everyone's favorite topic: money. Specifically, how companies think about money, track money, and make decisions about money.

If your eyes are already glazing over, I get it. When I was first a sysadmin, I thought finance was just "the people who make it difficult to buy the things I need." As a DevRel professional, you might think finance is "the people who keep asking me to justify my conference budget."

However, understanding finance might be the single most important business skill you develop. Because at the end of the day, no matter how amazing your DevRel work is, if you can't speak the language of money, you're going to struggle to advocate for your team, defend your budget, and demonstrate your value.

What Finance Actually Does

Finance manages the company's money. All of it. They track where money comes from (revenue) and where it goes (expenses). They plan for the future (budgeting). They make sure the company stays financially healthy. They report to investors or the board on the company's financial performance.

But finance isn't just about counting beans (though there is some bean counting). Strategic finance helps the company make smart decisions about where to invest resources. They're asking questions like:

"Should we hire more sales people or invest in marketing?"
"Can we afford to expand to a new market?"
"Which initiatives are giving us the best return on investment?"

For a company to survive, revenue needs to exceed expenses. Finance's job is to make sure that happens (or at least make sure the company is on a path to make it happen, because early-stage companies often operate at a loss while they're growing).

Meet the Finance Team

CFO (Chief Financial Officer): The top finance executive. They own the overall financial strategy and health of the company. They report to the CEO and often the board. When big financial decisions get made, the CFO is in the room.

VP Finance / Controller: Usually manages day-to-day finance operations. They might oversee accounting, financial planning, and the finance team members.

FP&A (Financial Planning & Analysis): These folks do the budgeting, forecasting, and financial modeling. When you submit your budget request, FP&A is reviewing it. When the company is trying to figure out if they can afford something, FP&A is running the numbers.

Accounting Team: They track and record all financial transactions, make sure bills get paid, ensure compliance with financial regulations, and generally keep the books in order.

How DevRel Interacts With Finance: Mostly through budget requests, expense management, and ROI discussions. Unless your company is really small, you probably won't interact with the CFO regularly, but you might work with FP&A on planning and budgets.

Understanding the P&L (Profit and Loss Statement)

A P&L is basically a report card for how the company is doing financially. Here's the simple version:

Revenue (money coming in)

minus Expenses (money going out)

equals Profit or Loss

If revenue is bigger than expenses, you have profit. If expenses are bigger than revenue, you have a loss.

Now let's break down the expense side, because that's where you live:

Cost of Goods Sold (COGS): The direct costs of delivering your product or service. For SaaS companies, this is things like cloud infrastructure, hosting costs, and support. Generally, you want this to be relatively low compared to revenue.

Operating Expenses (OpEx): Everything else it costs to run the business:

Sales & Marketing: Sales team salaries, marketing programs, advertising, events, tools
Research & Development (R&D): Engineering team, product team, technical infrastructure
General & Administrative (G&A): Finance, HR, legal, executive team, office costs

DevRel usually shows up in Sales & Marketing or sometimes in R&D, depending on where you report. Either way, you're an operating expense.

Cost Center vs Profit Center

Most DevRel teams are cost centers - meaning you cost money but don't directly generate revenue. Sales is usually a profit center because they directly bring in revenue (though they also cost money in salaries and commissions).

Being a cost center isn't bad! Most of the company is cost centers. But it does mean that during budget cuts, cost centers are scrutinized more heavily. This is why being able to articulate your value in business terms matters so much.

Budgeting: The Annual Stress Fest

Budgeting is the process of planning how much money each part of the company gets to spend. Most companies do annual budgets, often with quarterly reviews and adjustments.

The Budgeting Cycle usually goes something like this:

Leadership sets revenue targets and high-level spending parameters
Each department builds a budget showing what they need to spend to hit their goals
Finance reviews all the requests (which always add up to more than the company can afford)
Negotiation happens. Priorities get set. Cuts get made.
Final budget gets approved
Everyone complains it's not enough (it never is)
Throughout the year, actual spending gets tracked against the budget

Top-Down vs Bottom-Up Budgeting:

Top-down: Leadership says "Sales & Marketing gets $5M" and then that team figures out how to allocate it
Bottom-up: Each team builds their ideal budget and submits it up the chain

Most companies do some combination. You might be told "DevRel has a budget of $X" or you might be asked "What do you need for next year?"

Building a DevRel Budget

Your budget probably includes:

Headcount: Salaries and benefits for your team (usually your biggest expense by far)
Programs: Events, sponsorships, community programs, swag
Tools: Software subscriptions, community platforms, content creation tools
Travel: Flights, hotels, meals for conferences and events
Content Production: Video production, freelance writers, design services

When you build a budget, you need to:

Tie it to goals: "We need $X to do Y, which will result in Z outcome"
Show your math: "Three conferences at $10K each = $30K"
Prioritize: What's must-have vs nice-to-have
Be realistic: Under-budgeting doesn't help anyone

And here's what nobody tells you: always expect cuts. Budget a little high if you can, knowing you'll probably need to trim. But don't budget ridiculous things you don't actually need, because that damages your credibility.

Managing Your Budget Throughout The Year

Once you have a budget, you need to track it. Finance is definitely tracking it, and you should be too. Know at any given time:

How much you've spent
How much you have left
What big expenses are coming
Whether you're on track or over/under budget

If you're going to go over budget, flag it early. Finance hates surprises. If you're going to be way under budget, that's also worth flagging - sometimes you can reallocate or carry forward savings.

Essential Finance Terminology

CapEx vs OpEx: This is a big one.

CapEx (Capital Expenditure): Large purchases that are assets - things like equipment, buildings, major infrastructure. These get depreciated over time.
OpEx (Operating Expenditure): Day-to-day operating costs like salaries, subscriptions, travel, programs.

Most DevRel spending is OpEx. Why does this matter? Because CapEx and OpEx are treated differently for accounting and tax purposes, and companies often have different budgets for each.

If you want to buy a $50K piece of video production equipment, that's CapEx and comes from a different bucket than your $50K event sponsorship (OpEx). Understanding this helps you navigate budget conversations.

EBITDA: Earnings Before Interest, Taxes, Depreciation, and Amortization. This is a measure of operational profitability. Basically, it's trying to show how much cash the core business operations are generating.

Why should you care? Because companies that aren't profitable yet but are showing strong EBITDA growth are demonstrating they're on a path to profitability. This affects investment decisions and budget allocations.

Burn Rate: How quickly a company is spending money. Especially relevant for startups. If you're spending $1M/month and bringing in $500K/month, your burn rate is $500K/month.

Runway: How long the company can operate at current burn rate before running out of money. If you have $6M in the bank and a burn rate of $500K/month, you have 12 months of runway.

Why this matters to you: when runway gets short, budget cuts happen. Understanding runway gives you early warning signals.

CAC (Customer Acquisition Cost): The total cost to acquire a new customer. Add up all your Sales & Marketing spend and divide by number of new customers.

LTV (Lifetime Value): The total revenue you expect from a customer over their entire relationship with you.

LTV:CAC Ratio: This is super important. If it costs you $10,000 to acquire a customer (CAC) and they generate $30,000 in revenue over their lifetime (LTV), your ratio is 3:1.

Generally, you want this ratio to be 3:1 or better. Lower than 3:1 and you're spending too much on acquisition. Higher than 3:1 and you might not be spending enough (you could grow faster).

Why DevRel should care: If you can show that DevRel activities reduce CAC or increase LTV, you're speaking directly to metrics that executives obsess about.

Gross Margin: Revenue minus COGS, expressed as a percentage. If you have $100 in revenue and $30 in COGS, your gross margin is 70%. SaaS companies typically have gross margins of 70-80%+.

Why this matters: High gross margin means you have more money available for operating expenses (like DevRel). If margins are shrinking, operating budgets get squeezed.

How DevRel Costs Are Viewed

Let's be honest about how finance sees DevRel:

Headcount is usually your biggest cost. For example, if you have a team of 5 people with an average total compensation (salary + benefits) of $150K, that's $750K/year just in people costs.

Programs are visible and often questioned. That $50K conference sponsorship? Finance is asking "What do we get for that?" The more clearly you can connect program spend to outcomes, the easier budget conversations get.

Tools are usually easier to justify, especially if you can show ROI. A $10K/year community platform that supports 10,000 active developers is pretty easy math.

Travel is often the first thing to get cut in tough times. It's visible, feels expensive, and is easy to reduce. This is why many DevRel budgets got decimated during COVID.

Finance asks questions like:

"What's the return on this investment?"
"Could we get similar outcomes spending less?"
"Is this must-have or nice-to-have?"
"Can we measure the impact?"

The better you can answer these questions, the easier your budget conversations.

The Hard Truth About Budget Cuts

When companies need to reduce costs, they look at what they can cut with the least immediate impact on revenue. Unfortunately, DevRel often falls into this category because:

The connection to revenue isn't always direct or immediate
The impact of cutting DevRel isn't felt right away
It's easy to say "we'll just stop doing conferences for a year"

This is why business literacy matters. If you can articulate DevRel's impact in financial terms - "DevRel activities influenced $2M in pipeline" or "Our community reduces support costs by $X" - you're much better positioned to defend your budget.

Making The Business Case

When you need to advocate for budget, you need to speak finance's language:

Connect to revenue: "This program helps accelerate deals by X days, which means we close Y more deals per quarter"

Show efficiency: "This investment of $X reduces costs in other areas by $Y"

Demonstrate ROI: "Last year we spent $X on this and it resulted in Y measurable outcome worth $Z"

Frame in terms of risk: "Not investing in this creates risk of A, B, C"

Use benchmarks: "Industry standard for companies our size is X, we're at Y"

You don't have to have perfect data for all of this. But you need to be able to tell a credible story using numbers and business logic.

What Finance Wants From You

Honestly? Finance wants you to:

Stay on budget - Don't surprise them
Track your spending - Know your numbers
Justify requests - Explain the why
Show impact - Connect to business outcomes
Be realistic - Don't ask for things you can't defend

Finance people aren't the enemy. They're trying to make sure the company doesn't run out of money. Help them understand why DevRel is a good investment, and they'll often advocate for you.

What This Means For Your Work

Understanding finance doesn't mean becoming an accountant. It means:

You can build and defend a budget
You can have informed conversations with finance leadership
You can speak credibly about financial trade-offs
You can frame DevRel's value in financial terms
You can see early warning signals when budget cuts might be coming

Look, finance isn't the hippest part of business literacy. But it might be the most important. Because at the end of the day, companies are resource-constrained, and the teams that can effectively advocate for resources in financial terms are the ones that thrive.

Questions about budgets? Confused about the difference between CapEx and OpEx? Want to share your budget horror stories? Comments are open.

Previously: Part 3: Marketing 101

Next up: Product 101

DEV Community: Matty Stratton

I Contain Multitudes (and Also Three Git Repos)

The shape of it today

mattstratton.com: preserving twenty years of receipts

The field guide: my own posts plus the good stuff I wrote elsewhere

The newsletter: Buttondown does the sending, Astro just serves the pages

speaking.mattstratton.com: getting my slides back from a CDN I don't own

Making the talks searchable

Three repos become one

dev.to: ownership, not direction

The crosspost pipeline (and yes, this post is going through it)

A few weird-ass bugs, for flavor

The fun stuff: memory and gains

What's still on my plate

Your Agent Didn't Break Prod. Your Pipeline Did.

Continuous delivery is not continuous deployment

Put a gate on the release event, not just the merge event

An automated check is monitoring with a head start

The fallback: revert fast, and don't paint yourself into a corner

Someone still has to own saying "go"

Same guardrails, new reason to need them

What's Actually in My .zshrc (and Why)

The part that actually matters: AGENT_MODE

Secrets that don't live in plaintext

The gh alias that fixes a dumb problem

A shortcut for working an issue with Claude Code

atuin and starship deserve more than a name-drop

Aliases are underrated, actually

The stuff I'll just mention

Bonus: why there are three files, not one

Go poke around

Postgres Extensions Cheat Sheet: Replace 7 Databases With SQL

Enable Everything

Full-Text Search (Replace Elasticsearch)

Vector Search (Replace Pinecone)

Auto-sync embeddings with pgai

Hybrid Search: BM25 + Vectors in One Query

Simple weighted hybrid

Reciprocal Rank Fusion (for RAG applications)

Time-Series (Replace InfluxDB)

Lifecycle automation

Caching (Replace Redis)

Message Queues (Replace Kafka)

Alternative: SKIP LOCKED pattern (no extension needed)

Documents (Replace MongoDB)

Geospatial (Replace Specialized GIS)

Scheduled Jobs (Replace External Cron)

Fuzzy Search (Typo Tolerance)

What's Next

Why I'm Learning ROS 2 as a Database Person

How My Coworker Who Didn't Know 'cd' Shipped to Production

The agent is not the hard part

Rules are a suggestion

Skills are a habit

Hooks are a wall

The scaffolding is the product

Two things I owe you

How Do PostgreSQL Indices Work, Anyways?

It's a tree. Obviously.

Pages, not rows

The part nobody thinks about

Index-only scans (and why they're worth understanding)

Partial indexes (less is more)

So why does this matter?

The bigger picture

Coding Agents Are Actually Good at This One Thing

The Airtable Problem

Just Build the Thing

Why Internal Tooling Specifically

What About Retool?

Some Honest Caveats

Product 101: Your Secret Weapon for Understanding the Business

What Product Actually Does

Meet the Product Team: Roles You Need to Know

How Product Thinks About the World

The Product Roadmap

User Stories and Jobs to Be Done

Prioritization Frameworks

Success Metrics

Why Product Matters So Much to DevRel

The `gh` alias that fixes a dumb problem