Ben Balter

It's pronounced JIF. The Open and Async audiobook is out.

ben@balter.com — Tue, 08 Sep 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

The Open and Async audiobook is out. It’s read by a synthetic voice, which means that at some point a machine had to decide how to say GIF, with no help from me. It picked “jif.” Correctly. I have never been prouder of a robot.

In a bit, you’ll hear the audiobook both ways, the same line read by the same robot, and you can settle the argument yourself. Headphones on.

The fight only exists out loud#

GIF-versus-JIF is the one internet argument that text is structurally incapable of settling. You can go your whole career typing “GIF” and never once reveal which side you’re on, because the letters look identical in both camps. Type “actually, it’s pronounced jif” into a thread until your keyboard wears out, and nobody hears a thing. The fight only exists in sound. Record audio and it comes for you, wanting an answer before the next sentence. That’s how the audiobook became the first version of this book that could even have the argument. It took my side without being asked.

For the record: soft G. It’s “jif,” like the peanut butter.¹ Reasonable, thoughtful, wrong people say it with a hard G. We work together anyway.

Case in point. A paragraph can't do this.

There’s a chapter in the book about using chat well, and a section in it about emoji and animated GIFs being a kind of body language for text. A well-placed “that escalated quickly” carries something a paragraph can’t. The book already argues, in print, that GIFs matter. It just never had to say the word out loud. Then I made an audiobook, and it did, eleven times, in one chapter.

I recorded it wrong on purpose#

I wrote a whole book about working in the open, though, and the open-and-async answer to a disagreement is not to win the thread. It’s to ship the artifact and let people decide. I built the most literal version of that I could think of. I re-recorded the entire chapter with the narrator forced to say hard-G “gif,” beginning to end, and posted it, free, right next to the correct one. An entire edition in the wrong pronunciation, rendered for the heretics to enjoy their own wrongness. Same words, same narrator, one phoneme of difference. Pick your fighter. Mine already won.

The cat in question, for the record.

Ten seconds each, the same line both ways: “an urgent message from your manager gets the same screen space as a GIF of a cat playing the piano.”

Team JIF (the correct one)

Team hard-G (for the heretics)

The pronunciation was never the point. The GIF is. (share this quote)

That’s the point hiding inside the bit. The whole reason the chapter defends GIFs is that the shared reference does the work. Nobody who gets the joke has ever cared how you say the three letters. Arguing about the phoneme is bikeshedding the one part of the thing that carries no meaning at all. It’s impact over input, applied to a debate about peanut butter.

Both cuts live on the book’s feedback repository, which is where readers tell me what’s broken, what’s missing, and what actually landed.

Consider the hard-G edition a bug I shipped on purpose, a public service to the people who need to hear it. (share this quote)

About the robot narrator#

People kept asking for an audiobook, to listen at the gym or on a commute, and I’m a big audiobook fan myself. I did some of my best listening on parental leave, one hand on a stroller. I wanted the book to reach people that way too. What I didn’t have was a way to pay for it. A human narration doesn’t pencil out for me right now, not a professional’s four-figure, months-long project, and not the fifty-plus hours it would take me to read a hundred thousand words myself, badly. That left a synthetic narrator, and I’d rather say so straight than have you notice it later. No human voice actor, no studio.

Synthetic is the shortcut, and I’m not going to pretend it’s anything else. (share this quote)

Something real is lost with it. A good narrator doesn’t just say the words, they perform them: the timing, the dry aside, the breath before a hard sentence. My robot reads cleanly. It isn’t an actor, and if you’ve heard a great human narration, you’ll feel the difference. The bigger cost lands past my one book. Synthetic narration takes work from the people who do this for a living, and “it was cheaper for me” is exactly the logic that adds up to their livelihoods shrinking. I don’t have a clean answer to that.

A human narrator for this book is the goal, not a synthetic stand-in forever. If it earns its way there, it’ll get one. Until then, imperfect and shipped beats perfect and imaginary. Ship early, ship often.

Here’s where that leaves me: the voice is disclosed, it isn’t cloned from a real person, and a human (me) listened to all eleven and a half hours before it shipped.² Machine-narrated, human-checked. If a synthetic voice is a hard pass for you, I get it, and the ebook and paperback let you hear “jif” in your own head, at your own pace.

Get the audiobook#

That free chapter is a free sample, and I mean that literally. If you want the same synthetic narrator to read you the whole book, saying “jif” correctly the entire time, the full audiobook is out now. Eleven and a half hours of it, and not one hard G.

I am not going to win this argument. Nobody wins this argument. That’s exactly why you hand people the choice instead of typing one more reply, then go build the next thing. Even if one of the choices is objectively incorrect.

The right edition is the whole audiobook. The other one is just me being generous to the wrong ones.

So, which are you? Choose carefully. My narrator already did.

Steve Wilhite created the format at CompuServe in 1987, and when he accepted a lifetime achievement award he stood on a stage and said “it’s pronounced JIF.” The man who invented the thing gets to name it, and the hard-G crowd is out here overruling him. “But graphics has a hard G” is not the counterargument they think it is. It’s an acronym, not a word, and the inventor already ruled. Yes, there’s the peanut butter. Yes, I’m on that side too. I have made my peace with being right. ↩
The audiobook has its own QA suite. It transcribes the generated narration back to text, diffs that against the script, and flags mispronunciations, so a stray hard-G “gif” can’t slip into the correct edition. The machine reads. I still get the last ear. ↩

Out now

Liked this post? It's now a book.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Accessible by default: writing a book like software

ben@balter.com — Thu, 27 Aug 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

The build pipeline behind Open and Async is absurdly over-engineered: five formats out of one Markdown source, a real browser auditing every push, the works. I built it to satisfy my own compulsions, not a standard (or, more honestly, as an exercise in structured procrastination: elaborate tooling is a great way to not write the book it’s for). Then I went to check whether the ebook was actually accessible and found out it already was. It meets the Web Content Accessibility Guidelines (WCAG) 2.1 Level AA, spelled out in the book’s accessibility statement. Almost none of it was on purpose. Here’s what actually did the work, and what it missed.

Markdown won’t let you fake structure#

Most of accessibility, at least for a book, is structure. Headings that are actually headings, lists that are actually lists, and links that say where they go.

Markdown is inflexible about that, in the best way. ## is an <h2> or it’s nothing. There’s no font size to reach for, so there’s no way to make a line that looks like a heading without being one. Alt text sits on the same line as the image it describes, conspicuously empty when it’s missing.

Open a word processor and a heading is a style you’re welcome to apply, or you can select the line, bump it to 18pt bold, and move on. Both look identical on the page. Only one of them is a heading when assistive tech comes looking, and nothing in the editor tells you which one you made. I didn’t get real headings through discipline. I got them because my formatting doesn’t offer the other option. (share this quote)

And everything downstream inherits those semantics. Pandoc renders the same source into HTML and EPUB, and a Lua filter adds DPUB-ARIA roles on the way through. A screen reader knows a callout is a callout, and knows which list of links is the table of contents.¹

Markdown can’t check the parts you didn’t write#

Three weeks out from launch, the book came out to 575 pages. Print books get bound in signatures (big sheets folded down into 16 or 32 pages at a time), so an odd count meant a blank page at the end. Might as well fill it. At midnight I wrote a one-page back-matter spread (a QR code pointing at the book’s quote wall) and print landed at a tidy 576. Deploying on a Friday afternoon, in book form. It went about how you’d expect.

In the EPUB, that QR went out as a bare inline <svg>: not marked decorative, not given a name, just left for assistive tech to guess about, two files from my own conformance claims. Every build already ran the rendered book through axe-core, and every EPUB through EPUBCheck and Ace by DAISY.²³ All three came back green and the book shipped with it.⁴ Why they were green is the more useful half of the story.

Contrast doesn’t exist until the render#

Start with contrast, the cleanest example of something the source can’t check, because the source doesn’t contain it. Markdown has no color. The foreground comes from one CSS rule, the background from another (usually a different file, often behind a media query), and the pair only exists once the cascade has run. There’s nothing to grep, so the accessibility suite is Playwright driving a real browser over the built HTML, injecting axe-core into the page, and auditing the DOM the browser actually resolved.

That’s what makes the contrast rule possible. For every text node, axe reads the computed color, walks up the ancestors until it finds a background that isn’t transparent, blends in any semi-transparent layers it passes through, converts both ends to relative luminance (a weighted brightness value, not the raw RGB), and checks the ratio against WCAG 1.4.3: 4.5:1 for body text, 3:1 for large text (18pt, or 14pt bold). The pairs that fail are the ones nobody designed. (share this quote) Inline <code> inside a tinted callout. A muted caption on a page background that isn’t quite white. Two rules that are each fine alone and only meet in the render.

Then the whole audit runs a second time with page.emulateMedia({ colorScheme: 'dark' }), which flips prefers-color-scheme and hands axe the same DOM with an entirely different set of computed colors. Same tree, different palette, two verdicts. Both have to come back with no critical or serious violations, or validate-playwright goes red alongside the build jobs.⁵

What the checks can’t see#

What none of it can see is markup that never announced what it was. Every axe rule that fires on an unnamed image keys off either an <img> element or an explicit role: image-alt matches img, svg-img-alt matches svg[role="graphics-document"] and its neighbors. A <svg> with no role matches nothing at all, and EPUBCheck has no opinion about accessible names in the first place. The QR didn’t fail a check. There was no check for it to fail. (share this quote) Your checks have the same shape, whatever you’re building: they cover the categories somebody thought to name, and generated markup rarely announces itself as a category. Tagging this one decorative was my own postprocessing step’s job, and my rule was too specific.⁶

Accessible is a synonym for inclusive#

Strip away the acronyms and conformance levels and what’s left is a question about who gets to read the thing.

The reader sets the terms#

An accessible ebook reflows, so a reader sets their own font, size, spacing, and colors instead of squinting at whatever I happened to pick. I’m one of those readers, after enough years of staring at a screen all day. Its navigation works, letting anyone jump straight to the chapter they came for. It reads cleanly aloud, which matters as much for someone on a commute with the screen off as for someone using a screen reader. I can vouch for that part firsthand: I read the whole book screen off, listening straight through, while prepping the narration. That’s the one audit no checker in my pipeline runs, and the kind that catches what a green build can’t. A narrated edition turned out to be a much smaller lift than I’d budgeted for, because the structure that passed axe is the structure a voice follows. More on that soon.

Exclusion dressed as preference#

None of this is charity. A book that only works at my font size is making the same mistake as a decision that only happens in a meeting. The format quietly decides who gets to participate, and then everyone calls the result a preference.

Readers you’ll never meet#

Some of it pays off where I’ll never know. The EPUB’s metadata declares what the file is and what it conforms to, which is how the book ended up on Bookshare, the Department of Education–backed library where readers with print disabilities get books free, in DAISY, braille, or large print. I’ll never hear from that reader. Getting into that catalog cost nothing beyond accurately describing what I’d already built.

Those readers are all human. The same markup that serves them serves the software now reading your work, too. Every chapter in the book opens with a TL;DR, a fenced div in the source: ::: {.tldr}. The Lua filter gives it a DPUB-ARIA role, so assistive tech announces it as a summary instead of another paragraph of body text.

Structure is the interface#

That same TL;DR annotation feeds the book’s MCP server. Yes, the book ships one, so an agent can query it directly. A build script pulls 44 chapter TL;DRs, nine key-takeaway blocks, and the full outline straight out of the manuscript, with nobody hand-curating a machine-readable copy of any of it. One piece of markup, two consumers that have nothing else in common.

That overlap isn’t limited to my build script. Alt text is the only description a model has of your image. Headings are the boundaries a retrieval system chunks on. Link text is what an index actually reads. Neither a screen reader nor an LLM can see your 18pt bold. Both of them can read an <h2>. (share this quote) Semantic structure has become the interface for everything that isn’t a pair of human eyes. The accessible version of your writing and the machine-readable version turn out to be the same file.

The file has to open first#

The accessible file and the machine-readable file are only the same file if a reader can open it, which is why the book ships DRM-free everywhere it’s sold. DRM encrypts the EPUB so only an approved app can open it, and every tool downstream of that lock is on the wrong side of it: a screen reader the vendor doesn’t support, a text-to-speech engine, a braille conversion, an agent the reader points at a book they paid for. DRM is the one accessibility bug a reader can’t file. (share this quote) The structure only counts if the file is one they can open with whatever they read with.⁷

Steal this#

You don’t need my pipeline. Two decisions get you almost everything, and the first one is free.

Write in a format where structure is real. Markdown, if you like it. Your word processor’s actual heading styles, if you don’t. The goal is that faking structure takes more effort than doing it properly, so the lazy path and the correct path are the same path.

Then run one checker against the built output, on a schedule you can’t skip, one command wired into whatever already runs when you export or deploy. It doesn’t have to be axe and it doesn’t have to be thorough on day one. It has to be automatic, because the answer only helps while you still remember what you were doing.

Do both and accessibility stops being a heroic sprint at the end of the project. The ebook is accessible for the same unremarkable reason its links work: a machine checks, every build, and I can’t ship until it’s happy.

The whole thing is Markdown in Git, rendered by Pandoc into five formats and tested on every push. I wrote up the full pipeline separately, in more detail than anyone asked for. ↩
axe-core runs under Playwright against the actual built HTML, in light and dark, checking contrast, heading order with no skipped levels, alt text, link text that says where it goes, and a declared lang so a screen reader picks the right pronunciation. EPUBCheck covers spec conformance and Ace covers the accessibility metadata and structure that e-readers and library catalogs read. ↩
The book declares WCAG 2.1 Level AA and EPUB Accessibility 1.1 in its accessibility statement. Those are the same conformance levels the European Accessibility Act points to for ebooks, in force since June 28, 2025, which is how I ended up reading the conformance-reporting spec closely enough to learn that a11y:certifierReport has to be a <link rel> rather than a <meta property>. EPUBCheck failed my build until I got that one line right. Two things the checks still can’t fix, though. The claim covers only the ebook, since a fixed 6×9 print page doesn’t reflow for anybody. And there’s still no page list tying the ebook to the paperback’s page numbers, so citing the book by page means having the print edition on hand. ↩
Not from a check. All three passed it. I caught it weeks later while prepping the audiobook, going through the book with the screen off to decide what the narration should and shouldn’t voice. A QR with no accessible name is silent when read aloud, so it stood out by producing nothing at all. That screen-off read-through, which I get into later, is the one audit my pipeline doesn’t run. ↩
It’s a separate CI job rather than a step inside the build, so the audit runs in parallel with the EPUB, Kindle, and PDF builds instead of adding to the critical path. The whole graph finishes in about five minutes, which is the actual reason the checks survived: a gate slow enough to be annoying is a gate you start skipping. ↩
Fixed in v1.0.1. My decorative-image rule matched <img class="callout-emoji">, and the QR was neither an img nor a callout, so it walked right past. The EPUB postprocessing step now tags QR SVGs with aria-hidden="true", identifying them by the shape-rendering="crispEdges" attribute that’s unique to QR renders, so the cover art is left alone. Nothing is lost by hiding it. The URL is printed right underneath as a real link. ↩
It’s a checkbox at upload time on every store, and the default in at least one of them is on. Amazon also has a separate publisher-set flag for whether text-to-speech is allowed at all, which is a strange thing to be able to switch off on someone else’s behalf. ↩

Out now

Liked this post? It's now a book.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

How I over-engineered my book

ben@balter.com — Mon, 17 Aug 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

My book has a linter that yells at me for hyphenating “open source.”¹ It runs a battery of automated checks, rebuilds every format on each git push, and fails the build if I so much as imply I still work at a job I left. For a book. That one person wrote.

I didn’t set out to do this. Most people start a writing project by firing up Word or Google Docs, and I started down that same path. I even tried some purpose-built authoring tools, but every tool felt inferior to the ones I used as a developer every day. I did “the only reasonable” thing and threw all of them out, writing the whole book on Git, Markdown, and a CI build pipeline. If you’ve read how I over-engineered my home network (twice), none of this will surprise you.

I’ve been making websites for decades, so the leap was short: the same tools that build websites could build books, no last-minute magic-trick reveal required to abracadabra a standard Word doc into a full-blown book. There were missteps,² but in the end, I would not have written Open and Async any other way.

Content#

Naturally, the content itself lived as Markdown files in a Git repository. After all, that’s where I spend most of my day. I used VS Code, with a handful of prose extensions (listed below). Each chapter was its own Markdown file, and a single index.yml file defined the order, making it easy to re-order chapters or add new ones.

Practically, I wrote most of this book on an iPad (Codespaces in a browser tab, a Bluetooth keyboard, often nights and weekends while away from my desk), and the Git repository kept everything in sync no matter where I opened it. I could focus on the words, and a bad idea was one git revert away from gone.

Not to mention, I had real-time feedback on my writing right in my IDE from the various prose linters, just as I would have real-time feedback on my code from ESLint or Prettier.

Testing#

With content as code, the next logical step (and the point where “reasonable” quietly left the building) was to set up automated tests. Testing prose the way you test code is something I’d argued for years; this was me taking it to an absurd extreme. I did that two ways: real-time, and on push (CI).

Real-time#

Locally, as I typed, I ran several VS Code extensions all giving me real-time feedback. Specifically:

Markdownlint: Markdown syntax and formatting consistency
Harper³: grammar and word choice, entirely on-device
LanguageTool: grammar, punctuation, and style⁴
Vale: my own house-style rules and banned terms
Alex: insensitive or exclusionary phrasing
Write-good: weak prose, like passive voice, weasel words, and clichés

All six also ran in CI (Alex and Write-good folded into Vale there; more on that below). Together, they layered hundreds of curated style rules over a full grammar engine, all of it underlining my mistakes in real time, the way a red squiggle flags a type error.

On each push#

In addition to running those open source linters in CI (some blocking), I built a custom test suite of my own: a standalone Node script of content validators, a Vitest suite, and Playwright specs. The validators are the fun part. Each is a few lines that read the Markdown and push an error with a file-and-line pointer. My favorite: I don’t work at GitHub anymore, so any sentence claiming I still do fails the build.

// My time at GitHub has to read as past tense — present-tense
// employment claims about it fail the build.
function validateGitHubTense(files) {
  const patterns = [
    // "is/are ... at GitHub" — a current-employment claim
    /\b(is|are)\b[^.!?\n]{1,80}?\bat GitHub\b/i,
    // "works/leads/runs at GitHub" — current-employment activity
    /\b(works?|leads?|runs?|manages?|directs?)\s+(at|for)\s+GitHub\b/i,
  ];
  return flagLinesMatching(files, patterns);
}

That validator exists because I made the mistake once, which is the whole pattern. The first time an error got past me, I didn’t just fix that one sentence; I wrote a rule so I’d never have to catch it by eye again. It’s cattle, not pets for prose: don’t hand-nurse each chapter, govern the whole herd with policy. A mistake caught once becomes a check that sweeps every chapter and fails the build if it ever wanders back. That’s one of about thirty. Others I’m proud of:

validateOpenSourceHyphenation: “open source” is a noun, not a verb, and never hyphenated.
validateHypotheticalHooks: formulaic AI-tell openers (“Picture this…”, “Imagine…”, “Consider a…”) at the start of a paragraph.
validateSentenceStarters: three-plus sentences in a row opening with the same word.
validateNoBareUrlLinkText: no link whose visible text is just the raw URL.
validateCalloutBalance: the book speaks to managers and individual contributors, so a “For managers” callout has to have a “For ICs” counterpart nearby.
validateCrossReferences: every [text](#anchor) cross-reference resolves to a real heading.

…plus a couple dozen more for small caps, em-dashes, doubled words, en-dash ranges, TL;DR length, and every other tic I could name.⁵

One of these caught me. validateHypotheticalHooks flagged the opening of a paragraph I was certain I’d written myself. And I had. But reading it back cold, it did sound ghost-authored; I’d absorbed the cadence from reading too much generated text and produced a fluent imitation of nothing. A linter can’t tell good prose from bad. What it can flag are the patterns you reach for when you’ve stopped thinking, which is exactly the thing you can’t see in your own draft. Same reason I keep eslint around: it can’t tell good code from bad either, but it catches the autopilot mistakes your own eye skates right over.

All in all, the CI suite ran ~70 test files with 2,204 test cases and ~3,900 expect() assertions, plus another ~1,600 per-chapter structural checks from the validators above.

Audits#

The linters caught mistakes, but they couldn’t tell me whether the book repeated itself or whether a chapter was any good. For that I built a second layer of tooling: audits that judge the writing, not just check it. One thing they never did, though, was write it. Every word is mine; these tools are readers of last resort, catching what I’d stopped being able to see.

Duplication detection#

After reading the book over and over, I was convinced I’d repeated the same idea across chapters. I wanted proof, not a hunch, so I built three layers of duplication detection, each catching what the one before it misses:

jscpd: token-level copy-paste detection. Catches longer verbatim blocks I’d pasted between chapters, but nothing subtler.⁶
n-gram: tokenizes every chapter in index.yml, strips Markdown/Pandoc syntax, builds word n-grams (phrases of n words), and flags phrases appearing in more than one chapter (plus a “most-repeated stock wording” ranking). Two modes: cross-chapter (default --n) and intra-chapter (--scope=intra --n=8) for a chapter repeating itself.
semantic: the one the other two can’t do, the same point restated in different words. An on-demand LLM audit, designed so it never feeds the whole book to a model, runs three passes, each over small units:
- intra: one call per chapter: “where does this chapter restate itself?”
- cross: a single call over every chapter’s TL;DR, producing a map of conceptually overlapping chapters. A whole-book scan for the cost of one call.
- arguments: extract each chapter’s central claims one call at a time, then cluster the same argument across all chapters in one final call. Catches arguments made in body prose that cross misses.

Was I actually repeating myself? By this final pass the two mechanical layers came up clean, but they’d earned it: jscpd and the n-gram scan had already caught the copy-paste and recycled phrasing (a doubled motif here, a reused TL;DR structure there), and I’d fixed each.

What neither could see was the subtler kind: nothing was duplicated word-for-word anymore, just the same point in different words. The semantic pass caught that, and it was right: I’d made the same argument, that moving office habits online isn’t the same as working remote-first, in five separate chapters, on top of 166 smaller self-restatements scattered across 51 chapters. I’d paraphrased myself too well for anything cheaper than an LLM to catch me. (share this quote)

My hunch was correct; I’d just needed three escalating tools to prove what re-reading my own book to blurry-eyed exhaustion couldn’t.

Content audits#

Beyond duplication, a second set of tools graded the prose itself, split by how they judge. Some are probabilistic (an LLM reads the chapter and weighs in; run it twice and the findings can shift), and some are deterministic (rules and arithmetic, same input, same output, every time).

Probabilistic (LLM) audits#

The Claims lens caught what nothing else could, early. It stopped on a sentence claiming GitHub’s monthly all-hands “dedicated roughly half of each session to live Q&A.” That was a number I was certain of and had wrong; it was closer to a third, and the share moved around over the years. No linter flags that: it’s clean, confident prose that happens to be false. Only a reader asking “is this actually true?” catches it, and I’d have shipped it otherwise.

Claims is one of 20 single-purpose lenses in a “prose audits” test, a per-chapter LLM auditor where each lens asks one narrow question so the model can’t hand-wave a vague “looks good.” --lens=all runs every lens; --models/--rounds add a deduplicated multi-model and self-consistency panel, so a finding has to survive more than one model (or more than one run) to count. A sampling of the rest:⁷

Lens	What it catches
AI-tells	Phrasing that reads as machine-generated rather than my voice
Hook	Whether the opening does real work or is throat-clearing
Legal	Legal or reputational risk (naming names, unverified claims)
Dated	Perishable references that will age badly (“recently,” “this year”)
Global	Idioms and cultural assumptions that trip up non-US readers
Dual-audience	Whether a chapter serves managers and individual contributors
Promise	Whether the chapter delivers on the book’s core promise

Separately, I also had a traits analysis test, which scored each chapter on persuasion and engagement traits, catching prose that was technically clean but flat so I could give it another (human) pass.

Deterministic audits#

I ran these after a round of editing, to see whether the book was improving as a reading experience: chapter- and paragraph-length distributions, whole-book reading time, a hard EPUB size budget (Kindle penalizes oversized files on delivery), a book-wide consistency checker, and a stats dashboard whose --check mode fails the build unless every “attention item” (a chapter missing a TL;DR, an unbalanced callout) sits at zero.⁸

Together, these turned “is the book actually getting better?” from a gut feeling into a number I could watch move between drafts.

The writing dashboard for Open and Async: summary cards reading 99,651 total words, 399 minutes reading time, 72 chapters, 1,384 average chapter words, 103 manager callouts, 102 IC callouts, 123 pro tips, and 62 objections, with a green "No issues found, all content chapters look good!" all-clear at the bottom.

Design#

I am far from a designer, and I’d never published an ebook before. I had no idea how they worked beyond reading many of them. Two aha moments changed the way I thought about publishing:

An ebook is a website in a trench coat (share this quote). Ebooks are just HTML and CSS, albeit a very stripped-down version.⁹ If you can make a website, you can make an ebook.
A print book can be one too, with enough effort. CSS natively has powerful @media print and @page rules, including left and right page styling, title pages, page numbers, and more.

For the interior design, I reached for Tailwind CSS, not because it’s built for books (it isn’t), but because it’s what I already use every day. @tailwindcss/typography gave me a typographic baseline to start from instead of a blank page.

One note: I purposefully hired a human designer for the cover. For a book about being authentic, the first impression had to be authentic.¹⁰

The invisible leak#

Styling every format from one stylesheet has a failure mode: CSS meant for one format bleeding into another. To keep my e-reader tweaks away from the paperback, I scoped each of them to @media not screen. But WeasyPrint (the HTML/CSS-to-PDF engine that draws the paperback, more on it below) renders the print PDF with media type print, and print is “not screen,” exactly as the spec says. So two of those e-reader rules matched anyway and quietly bled into the book: a tighter line-height on callout paragraphs, and a box-decoration-break change that dropped the repeated padding on any callout that split across a page.

Neither was visible. Nothing looked broken. But each shaved a sliver of vertical space off every callout, and the book slowly deflated from 576 printed pages to 567. I only found out because the print PDF is pinned to exactly 576 pages¹¹ and the build went red: a page-count gate written to protect the cover spine, catching a CSS bug it was never designed for. Two formats from one stylesheet is a gift, right up until the cascade forgets which format it’s in. (share this quote) The fix re-pins the original values in a print-only block, loud with !important so the leak can’t win.

Tests#

The design and layout got a test suite as well, driven by Playwright against the built HTML, so it checks what actually renders, not what I hoped the CSS did. Two categories:

Accessibility (axe-core)#

The axe-core engine runs over the rendered book in both light and dark mode against WCAG 2.1 AA: no critical or serious violations, AA color contrast in either scheme, alt text on every image, logical heading order, discernible link text (no bare “click here”), and a declared lang attribute so screen readers pick the right pronunciation. It’s the test:a11y gate, enforced in CI as validate-playwright. Accessibility earned more than a subsection here. It has its own accessibility statement, and a dedicated deep dive is coming.

Visual & layout regression (Playwright)#

These assert that the actual computed styles match the design intent (the details that break quietly and never show up in a diff): the title page renders centered with a lighter-weight subtitle; the table of contents is a real nav with the doc-toc role and working links; every callout type has its own unique left-border color and auto-generated label prefix; and small caps get real font-variant: small-caps, not just a class name.¹²

None of this is glamorous. It’s exactly the kind of thing that breaks silently in a Friday CSS refactor and doesn’t surface until a reader emails you.

Building#

We’ve got clean Markdown, and a test suite that ensures the content is clean, but we still need to get it into a format that can be published (EPUB, Kindle, paperback in two flavors, and web). Core to that custom build pipeline was Pandoc, a universal document converter that can read Markdown and spit out just about anything else. I used Pandoc as the engine, but Pandoc alone gets you a generic document. Turning that into five store-ready formats took a pile of custom tooling:

A reproducible toolchain#

Pandoc is only the engine. The full build also needs WeasyPrint to draw the PDF, Ghostscript to convert it, and a pile of Noto fonts for full Unicode coverage: a gnarly stack of native dependencies to install by hand. The whole thing therefore lives in a Docker image and a dev container, pinned to an exact renderer version (a detail that matters more than you’d think, see the page-count gate below). That container is also why I could draft the book from an iPad: the heavy toolchain ran in Codespaces, not on my lap.

Pre-processing (before Pandoc sees the text)#

Everything starts on a throwaway copy of the source tree, so these transforms never touch the real chapters. A couple of scripts massage that copy before Pandoc runs: stamping each build with its commit SHA, turning inline links into numbered footnotes for print (a hyperlink is useless on paper; a footnote with the full URL isn’t), and reshuffling the chapters per format so the EPUB gets shareable quote links while print and Kindle get a QR share page instead.¹³

CSS pipeline#

One Tailwind stylesheet (src/style.css) compiles through PostCSS to dist/style.css, so screen, print, and EPUB all start from the same source of truth. Each format then takes a different slice: strip-page-rules.js derives a cut-down stylesheet for EPUB, stripping the CSS Paged-Media features (@page, target-counter(), oklch(), custom properties) that Kindle and EPUBCheck choke on.

Lua filters (the interesting part)#

This is the part I didn’t expect to love. Pandoc parses everything into an abstract syntax tree (AST) and lets you rewrite that tree with small Lua scripts before it renders, so format-specific tweaks live in code, not smeared through the prose. Deleting a node, for instance, is just returning an empty table:

-- strip-comments.lua: drop editorial HTML comments so my notes-to-self
-- never ship inside the published .xhtml. Returning {} removes the node.
function RawBlock(el)
  if is_html_comment(el.format, el.text) then
    return {}
  end
end

The rest are variations on that idea:

add-div-titles.lua: injects the callout labels (“TL;DR: ”, ”💡 Pro-Tip: ”, ”👔 For managers: ”) and DPUB-ARIA accessibility roles, so those labels aren’t hardcoded in every chapter and can differ per format.
Emoji, handled three ways: color emoji render fine on screen, but strip-emoji-kindle.lua swaps them for Kindle-safe glyphs (e-ink has no emoji font) while body-emoji-images.lua turns them into inline Twemoji images for the print PDF.
tagline-share-links.lua: appends a “share this idea” permalink after each of the book’s bumper-sticker lines in the EPUB.

The dark box#

Turning emoji into images solved the missing-font problem and created a subtler one. Twemoji’s PNGs are transparent, but the RGB underneath the transparent pixels is dark slate: invisible if a renderer honors the alpha channel, an ugly charcoal box if it doesn’t. And whether a renderer honors alpha turned out to depend entirely on where the book got opened.

On Kindle, my first fix baked the callout’s background color into each PNG and dropped the alpha outright. It looked perfect on a light-mode Paperwhite and terrible on Kindle for iOS, which does honor transparency and doesn’t paint the callout tint behind the image, so every emoji got a colored rectangle instead of a dark one. I’d traded one box for another. What shipped keeps the alpha intact but rewrites the RGB of every fully transparent pixel to white: renderers that honor alpha get clean transparency; the ones that flatten it get white, which vanishes on a white page.

The print PDF needed the opposite fix. Ghostscript converts the paperback to PDF/X-1a with -dNOTRANSPARENCY (required to keep the text as selectable vectors instead of a 300-DPI bitmap) and that flag always drops the alpha. So there, transparency is the enemy: each emoji is flattened onto the exact color it sits on (the callout’s gray, or white for body text) with no alpha at all, so there’s nothing to drop and no box to reveal. The same bug needed opposite fixes: one runtime might drop the alpha, the other was guaranteed to. (share this quote) A Python script bakes both sets at build time.

It’s the most ordinary bug in the world. Mine just happened to be in a book.¹⁴

Rendering & post-processing per format#

With the tree transformed, each format renders down its own path, and the paperback takes the longest road. HTML and the PDF both render through Pandoc, but the PDF is drawn by WeasyPrint, an HTML/CSS-to-PDF engine, so I typeset the entire book with the same box model I’d use for a web page. The EPUB goes a different way: Pandoc embeds WOFF2 font subsets, then postprocess-epub.js repackages it to stay valid and small. And the paperback keeps going after everyone else has stopped, out to Ghostscript to become PDF/X-1a:2001 (CMYK color, an embedded USWebCoatedSWOP ICC profile, flattened transparency), the archaic print standard IngramSpark (the print-on-demand distributor) won’t live without.

That same 576-page gate does double duty here. check-pdf-page-count.js pins the count and fails the build the moment the paperback drifts off 576 pages: cheap insurance against a stale page count shipping as a wrongly-sized cover spine.

That’s five publishable files out of one Markdown source¹⁵, which raises the obvious question: how do I know any of them are actually correct?

Testing the build#

The prose linters keep the words honest; a larger slice of that Vitest suite keeps the build honest. A Pandoc upgrade or a stray line of CSS can silently break a format, and I wouldn’t find out until a reader’s Kindle rendered the wrong font. The tests check the machinery: that each transform does what it claims, and (the biggest cluster by far) that typography hasn’t quietly drifted across small caps, table borders, print contrast, dark mode, and the e-ink emoji fallback. Each is a test because each is a way I’ve watched a build look fine and render wrong.

But unit tests only prove my code is right, not that the output is valid. So each artifact also runs through the same validators the stores themselves use, and a rejection happens on my laptop, not on upload day. Every EPUB goes through EPUBCheck, the validator every store runs on upload, and Ace by DAISY, an accessibility audit built specifically for ebooks; the built HTML gets crawled by lychee for link rot and run through an HTML validator before malformed markup can become a malformed ebook.

None of this is something I have to remember to run. Every push to main kicks off 14 parallel CI jobs: build the CSS, then the EPUB, Kindle EPUB, print PDF, PDF/X-1a, HTML, and DOCX side by side, and validate each as its artifact comes ready. A green check means every format built and passed every gate; a red X means something’s off before I’ve even alt-tabbed away.

# build.yml — mostly independent jobs, so CI runs them in parallel
jobs:
  build-epub:            # → dist/book.epub
  build-kindle:          # → Kindle-specific EPUB
  build-pdf:             # → 6"×9" paperback PDF
  build-pdf-ingramspark: # → PDF/X-1a for IngramSpark
  build-html:            # → web preview
  validate-epubcheck: { needs: build-epub }
  validate-ace:       { needs: build-epub }
  validate-playwright: { needs: build-html }

A GitHub Actions run of build.yml with fourteen parallel jobs (lint-and-test, detect-duplicates, build-css, build-epub, build-kindle, build-pdf, build-html, build-docx, and Build PDF/X-1a, then validate-epubcheck, validate-ace, validate-links, validate-html, and validate-playwright), every one passing green, total duration five minutes eight seconds.

And because every build stamps its commit onto the title page, the book is versioned like software. I’m on release 1.0.1, with a tag and a changelog, not a graveyard of final_v3_revised_ACTUALLY_FINAL.docx files. A typo fix is a point release.

Publishing#

For all that automation, the actual publishing is almost entirely click-ops. There’s no git push to production. Each store (Amazon’s KDP, IngramSpark for bookstores and libraries, Draft2Digital for Apple Books and Kobo) wants you to log into a web dashboard, upload the EPUB and the print PDF by hand, and re-enter the same metadata (title, description, BISAC categories, keywords, price) into a slightly different form each time. My pipeline builds a flawless artifact, and then I upload it like it’s 2009. (share this quote)

A few things kept even that part honest:

I’m my own publisher. I formed an LLC and bought my own ISBNs (one per format) so the catalogs list me as the publisher, not a free platform ISBN with the retailer’s name on it. That also means none of the vendor lock-in that comes with one, since a free ISBN only publishes through the platform that handed it out.
Wide, not exclusive. I skipped Amazon’s KDP Select, which pays a bit more in exchange for locking the book to Amazon, so the book could be available everywhere at once.
The metadata is versioned too. The description, categories, and keywords live in the repo (a single source of truth I can diff), and an ONIX feed is generated from it for the channels that accept one. I still paste it into web forms by hand, but at least I’m pasting from a file under version control.

Looking forward#

The nice thing about a book that builds like software: the same machinery keeps paying off after launch.

Translations. Because the content is structured Markdown, translating it is closer to localizing an app than retyping a manuscript. I’ve got a pipeline (Brazilian Portuguese, Latin American Spanish, German) that drafts a translation of the finished English book, pins every heading ID so cross-references don’t break, enforces a glossary so key terms stay consistent, and back-translates the result to check it against the original: the same trust-but-verify instinct as the prose linters, just across languages.¹⁶
An audiobook. If I record one, turning 100,000 words into narration opens a whole new class of bug: mispronunciations. So the audiobook has its own QA suite. It transcribes the generated audio back to text and diffs that against the script, checks phonemes on the tricky words, and audits pronunciations, all wired into their own CI workflows. It’s a snapshot test, aimed at my own voice.¹⁷
Releasing the tools. Almost none of this is specific to my book: the validators, the Lua filters, the whole pipeline. I’d like to clean them up and put them out as open source (a noun, no hyphen), so the next person doesn’t have to build it from scratch. And none of it would exist without the open source projects it already stands on. The whole book is other people’s generosity, compiled.¹⁸

Conclusion#

One Markdown source, a linter with opinions, and a build that yells when I’m wrong. Here’s what all that over-engineering added up to.

By the numbers#

Metric	Count
Words	~100,000 across ~70 chapters and sections
Print length	576 pages (6”×9”)
Published formats	5 (plus a DOCX I don’t ship)
Tests	~70 files, 2,204 cases, ~5,500 automated checks
CI jobs per push	14, in parallel
Style rules	~300 covering 500+ banned terms, over a 5,000-rule grammar engine
Commits	5,000+ to get here
Books	1 (frankly over-engineered, but fun)

The tooling outgrew the book, too. I pointed the whole apparatus at this blog’s fifteen-year archive and caught a 2011 post that had been saying “its clear” where it meant “it’s clear” the entire time, the exact missing apostrophe my linter now flags on every keystroke. Thousands of people read it; nobody ever mentioned it. You don’t find out. You have to go looking. (share this quote)

And it wasn’t only the tooling that transferred. The habits did. The instincts I sharpened here (treat a mistake caught once as a rule that catches it forever, keep a human in the loop on anything a machine drafts, make the build the source of truth) have already found their way into how I run my other projects, this site included.¹⁹

I’m not going to tell you to write 5,500 tests for your novel. For most books, most of this is wildly disproportionate, and that’s the point. I did it because the marginal cost of one more check, one more format, one more validator was a few minutes and a little curiosity, and because doing it the developer way meant I could write from an iPad away from my desk and trust that main was always shippable. If you spend your days shipping software, the tools you already know will take you further than you’d expect. The publishing industry starts with a word processor. I started with a Git repository (share this quote). And I’d start there again.

What would you over-engineer, if you pointed your own tools at it?

A colleague called me out on “open-source” in an early draft; I vowed never to make the mistake again, then made a linter swear to it for me. ↩
Chief among them: I lost a weekend to LaTeX, on the theory that the tool serious typesetters swear by had to be worth learning. It is, if you typeset for a living. For me it was a wall of arcane macros and inscrutable errors to approximate a layout CSS gave me in an afternoon. I bailed and never looked back, which is how the whole book ended up drawn with a web box model instead. ↩
I’m a terrible speller so I also ran CSpell in VS Code, which shared a custom dictionary with Harper. ↩
Self-hosted, so it ran on-device too, well, in the Codespace. ↩
The roster, grouped. Typography: validateSmallcaps and validateEscapedSmallcaps (acronyms rendered in small caps, not accidentally escaped), validateEmDashes, validateNumberRangeDashes (en-dash ranges), validateQuotePunctuation, validateListPunctuation, validateBoldKeywords. Structure: validateHeadingHierarchy (no skipped levels), validateDuplicateHeadings, validateParagraphLength (no walls of text), validateMinOpenerLength, validateSectionIntros / validateSectionIntroHasLead / validateSectionIntroFinalLead / validateSectionIntroNoTldr (section intros lead into the content without restating the TL;DR), validateTldrLength, validateChapter, validateIndexIntegrity (index.yml matches the files on disk). Links & references: validateCrossReferences, validateNoBareUrlLinkText, validateFootnotes, validateAcronymExpansion (expanded on first use). Callouts: validateCalloutBalance (managers paired with ICs), validateCalloutDivs, validateRoleCalloutLabels. Voice & anti-AI: validateGitHubTense, validateOpenSourceHyphenation, validateHypotheticalHooks, validateSentenceStarters, validateDoubledWords. Housekeeping: validateNoTodoMarkers, validateNoTransitionTodos, validateBuildIdentifiers, validateSSML (audiobook markup). ↩
jscpd is not prose-specific. It’s a great way to DRY up code. ↩
The other twelve, briefly: Consistency (drift in the book’s own conventions), Taglines (bumper-sticker lines worth pulling into callouts), Proofread (typos and mechanical slips), Cross-reference (broken “see chapter X” pointers), Acronyms (unexpanded on first use), Jargon (the “explain it to a new hire” test), Alt-text (missing or non-descriptive), Evidence (assertions with no why or how), Structure (heading hierarchy), Readability (sentences hard to parse on one read), Inclusive (non-inclusive language, judged in context), and Emphasis (overused bold, italics, and scare quotes). ↩
audit-chapter-lengths.js / audit-paragraph-lengths.js flag outlier chapters and walls of text; reading-time.js clocks each chapter and the whole book at 238 wpm (average adult non-fiction speed); check-epub-size.js enforces the size budget; consistency-check.js settles “open source” vs “open-source” and “async” vs “asynchronous” book-wide; and writing-dashboard.js renders it all to HTML. Plus a handful of advisory local checkers (proselint, GNU diction, and GNU style) for wordiness and readability stats. ↩
Not just a metaphor. Kindle’s modern format (KF8/AZW3) is rendered by a WebKit-based engine (the same rendering lineage as Safari) down to Amazon’s own -webkit- CSS extensions; a Kindle book really is a little offline web page. But the engine ages slowly across a long tail of e-ink models still in readers’ hands, so the HTML and CSS it reliably supports lag years behind the modern web, hence “very stripped-down.” ↩
AI could have generated something competent, and that was exactly the problem: competent and generic is the failure mode I spent 5,500 checks scrubbing out of the text. The cover is the one thing a reader judges before reading a word, so it was the last place I wanted a machine’s default taste. A human designer got the brief; the algorithm didn’t. ↩
Locking the length isn’t fussiness. The whole physical book is built around that number. A page count sets the book’s thickness, so the spine width, and the cover art wrapped around it, is computed from it. Drift off 576 pages and the cover no longer fits the spine: fixing it means a round trip back to the human designer to re-render the wrap, not a one-line code change. More on that gate below. ↩
The rest, in the same spirit: the copyright page is present and bottom-aligned on screen; H2 is larger than body text and H3 smaller than H2; links are underlined, code blocks have a dark background and inline code a visible one, and blockquotes carry a left border; and body text uses the Tailwind Typography prose class. ↩
update-revision.js stamps the build SHA and version onto the title page, so every copy traces to its commit; links-to-footnotes.js does the print link-to-footnote rewrite; and a per-format manifest handles the reshuffle. Same source, subtly different books. ↩
I spent years at GitHub, where emoji are practically part of the syntax (reactions, :shipit:, an emoji picker in every comment box) and they turned up a fresh encoding edge case like clockwork. Emoji, uh, find a way. ↩
The build actually emits a sixth artifact (a DOCX) which I used to gather early feedback from reviewers in Word, with track changes and comments. It’s a working format, not something I publish. ↩
The pipeline drafts and self-checks, but it doesn’t get the final word. If I decide to actually publish any of these, a human native speaker will review and proof the translation first: machine-assisted, human-approved. ↩
The QA suite catches drift, but a transcript diff can’t hear a flat line reading or a subtly wrong emphasis. If I release it, I’ll listen to the finished narration end to end, every word ear-checked by a human before it ships. ↩
The full list, with thanks to their maintainers: Tailwind CSS and Tailwind Typography, Pandoc, WeasyPrint, Ghostscript, qpdf, Poppler, Source Serif 4, Source Sans 3, and Source Code Pro by Adobe, Twemoji, ImageMagick, sharp, SVGO, PostCSS and cssnano, Remark and Retext (and countless ecosystem plugins), textlint, markdownlint, Prettier, Harper, Vitest, Playwright and axe-core, Ace by DAISY, EPUBCheck, htmlproofer, lychee, html-validate, Pillow, LanguageTool, Vale, proselint, GNU Diction, yamllint, js-yaml, jscpd, and just. ↩
Case in point: my résumé is a print-only web page the build renders straight to PDF, a different engine than the book (headless Chrome here, WeasyPrint there), but the same “an ebook is a website in a trench coat” idea, pointed at paper. ↩

Out now

Liked this post? It's now a book.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Open and async on the Overcommitted podcast

ben@balter.com — Tue, 28 Jul 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

A decision without a URL gets relitigated forever. (share this quote) What makes a remote engineering team actually work comes down to how you communicate, not where you sit. Most of it is a set of habits you can build.

Those habits are the backbone of Open and Async, and the throughline of a conversation with Bethany Janos and Erika Eggemeyer on the Overcommitted podcast: why async is the operating system and remote is the hardware, how to run a stack where chat coordinates but issues and discussions carry the durable decisions you can point to six months later, and why you measure outcomes instead of keystrokes.

The conversation runs to the nerdier end too: the absurd, over-engineered CI pipeline behind the book (a rabbit hole that’s getting its own post soon), the aspirational automation that syncs my standing desk to my calendar, and where AI actually belongs when you write.

You can listen to the full conversation over on the overcommitted website, or wherever you get your podcasts.

Out now

Liked this post? It's now a book.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Open and Async: the remote-work playbook is out

ben@balter.com — Tue, 21 Jul 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

Most companies didn’t go remote. They shipped everyone a laptop, bolted Zoom onto the same approval chains, and called it a day. That wasn’t remote work—it was office work in sweatpants: the same meetings, the same status theater, the same “quick syncs,” just piped through a webcam. (share this quote)

Working from home ≠ working remotely. (share this quote) There’s a world of difference between being forced out of the office and intentionally building a distributed, async culture. That difference is what Open and Async is about—and as of today, you can read it.

Open and Async is the opinionated, practical playbook for the two practices that make distributed work actually work: working in the open and communicating asynchronously. Async is the operating system; remote is the hardware. It’s how the next generation of tech leaders already think—and it’s a learnable skill for everyone else.

If you’ve spent any time on this blog, the argument will feel familiar—the book grew out of these posts. It’s where the scattered pieces finally become one ordered playbook: the full case, start to finish, with the connective tissue no single post ever had room for. Everything you’ve read here, plus the two-thirds that never made it to the blog.

What separates teams that thrive#

More than a decade of remote-first work at GitHub made one thing clear: the tooling was never what separated the teams that thrived from the ones that just survived. Companies would adopt those workflows wholesale—add issues and pull requests on top of a hierarchy-driven approval process—and wonder why nothing changed. Tools: right. Bottlenecks: intact. The result was Zoom fatigue plus all the old dysfunction, now faster.

The teams that pulled ahead did something different. They gave every decision a URL so context survived reorgs and departures. They treated meetings as escalation, not default. They worked loudly so impact was visible without anyone performing busyness. None of it was intuition—it was a set of repeatable practices, and Open and Async is those practices, written down so you can put them to work.

Who it’s for#

Two audiences, both in remote and distributed work:

Managers—build teams that ship without constant synchronous coordination, and retain your best people by respecting their time, focus, and intelligence.
Individual contributors—become visible, effective, and promotable on the strength of your work, not the luck of your seating chart. Interviewing at a remote-first company? This is the playbook they wish you’d already read.

What’s inside#

A few of the things you’ll learn how to do:

Treat meetings as a point of escalation, not the default—and reclaim the hours you’re losing to “quick syncs.”
Give every decision a URL so context survives reorgs, departures, and Slack purges.
Run 1:1s, weekly reports, and career conversations that aren’t a tax on everyone’s time.
Lead—whether or not you have direct reports—by showing your work.
Hire, onboard, and transition teams to remote-first work without losing what made them good.

It’s 575 pages, and the method ships as more than a manuscript. There’s even a Model Context Protocol (MCP) server that drops the book’s async-first practices straight into your editor, so an AI agent can draft a decision doc or pressure-test a status update against the same rubric the book teaches.

Stop digitizing the office. Start building something better. (share this quote)

Out now

Liked this post? It's now a book.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Work loudly

ben@balter.com — Tue, 14 Jul 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

You did the work. The hard kind—the three weeks of chasing a race condition that only showed up under load, the careful refactor that made the next six features trivial, the quiet design call that saved the team a quarter of pain. Then your performance review comes around, and your manager—who likes you, who’s genuinely on your side—can’t quite say what you did. Not because the work wasn’t real. Because they never saw it happen.

This is the part nobody warns you about when you go remote: In an office, some of your visibility was free. People saw you at the whiteboard, overheard you unblock someone in the kitchen, watched you stay late. None of that was a measure of your impact—but it added up to a vague, ambient sense that you were doing things. Take away the building, and that ambient signal goes to zero. The work doesn’t get less valuable. It gets less visible. And invisible work is, for every practical purpose—promotion, credit, getting pulled into the interesting projects—work that didn’t happen. (share this quote)

Work in the open, not in a summary#

The instinct most of us have is to fix this at the end. Do the work heads-down, then write the big summary, present the finished thing with a bow on it. That’s backwards. By the time you’re presenting, the interesting part is over—the reasoning, the dead ends, the moment you realized the obvious approach wouldn’t work. You’re narrating a conclusion when the value was in the process. This is showing your work applied in real time. The fix is to work loudly: make the work visible as you do it, in shared and durable places, not after the fact in a status update nobody reads. (share this quote)

In practice that means thinking out loud where others can see it. The issue you open before you start, with what you’re trying and why. The pull request description that explains the approach, not just the diff (it may even be longer than the diff). The “here’s where I’m stuck, here’s what I’ve ruled out” message in a public channel instead of a private one. The rough draft shared at 40% instead of the polished thing shared at 100%. You’re not adding a layer of reporting on top of the work. You’re doing the work in the open, where it leaves a trail.

I’ve opened a few thousand issues; the ones that mattered most were the ones I opened before I knew the answer. The tell: if it only lives in your head or a DM, it isn’t loud yet. (share this quote)

Like a bear bell#

I think of it like a bear bell (bells you attach to your pack when hiking bear country). You don’t ring it to show off—you ring it so the bear hears you coming. The danger on the trail isn’t the bear—it’s the startled bear, the one you surprised rounding a blind corner. Every org has them: the stakeholder who learns about your decision after it ships, the team that discovers from the changelog that you rerouted around them. Surprise people like that, and they don’t get curious—they get defensive, territorial, loud.

I learned this the hard way. GitHub’s (then) CEO and General Counsel once DM’d me about an urgent, time-sensitive feature. I assumed my own leadership was already in the loop, so my team went straight to work—focused on the time-critical work, not the time-critical communication. Our leadership first found out when the feature was ready to ship and we kicked off the launch: docs, blog post, the rollout. It was not good. The feature went out—there was an executive mandate behind it—but the launch had made the people I reported to look out of the loop in front of their peers. I don’t know that their trust in me ever fully recovered.

Working loudly is the bell: the low-effort, ambient signal that you’re on the trail and headed their way. Your work and your decisions reach people as something they saw coming instead of an ambush, and they get the chance to respond early and productively.

Loud, not bragging#

It’s the objection I hear most.

The payoff compounds#

The payoff is bigger than getting credit, though you’ll get that too. (share this quote) When your work is visible in progress, people can help. Someone spots the bug in your approach before you’ve sunk three days into it. A teammate who solved the same problem last quarter drops a link. The senior engineer who’d never have been pulled into a private thread weighs in on the public one. Loud work compounds—it invites collaboration that silent work never gets the chance to.

I like to joke that the hardest part of open source is googling to find out whether someone already solved your problem (share this quote) before you spend a week solving it yourself. Inner source—the same habits inside a company—is no different: work loudly so others can find you, and look around so you find them before you redo their work.

Managing without surveilling#

I once led a team at GitHub that split, roughly down the middle, into two styles. Half of them did everything—and I mean everything—in issues. Weekly reporting was a GitHub search on my end: their work was already written down, already visible, and the interesting opportunities tended to find them. The other half worked mostly in DMs and in their own heads. Some weeks I’d get a crisp update; some weeks their work never reached the people above me at all, because I had nothing to point to. Same team, same caliber of work. At end-of-year reviews, that gap didn’t stay small—it compounded into the story each person’s year got to tell.

If you manage people: this is how you lead without surveilling. You don’t need standups-as-status-roundup or “just checking in” pings when the work is legible by default—you can see it, link to it, build on it. You get to evaluate your team on what they actually shipped instead of who happened to be online when you looked. Make the work visible, and you can finally reward outcomes instead of hours. The alternative—rewarding the people who are merely around—is how good remote engineers quietly conclude they’re better off somewhere else.

The trail test#

Here’s the test, on the work you’re doing right now: could your manager write your review from the trail alone—not from your memory, not from a meeting you’d have to attend, but from what you’ve left behind? If yes, you’re working loudly. If no, the work might be excellent, and it’s still happening where the one person whose job is to see it can’t. Ring the bell. (share this quote)

Out now

This post is adapted from my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Reorgs happen

ben@balter.com — Sun, 07 Jun 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

In thirteen years at GitHub, I was part of 25 reorgs and reported to 13 different managers. That’s a new org chart roughly every six months and a new boss roughly every year, like clockwork.¹

I know these numbers because I tracked them. What started as a humble spreadsheet eventually metastasized (as my side projects tend to do) into a full statistical forecast model that predicted the date of my next reorg with confidence intervals.² When colleagues asked how I stayed so calm during shake-ups, the honest answer was that I’d seen the data: reorgs are a disruptive fact of life in tech, and they can be a major source of stress and uncertainty. But they don’t have to be.

Why reorgs happen#

Most reorgs aren’t about you. They’re rarely malicious, and honestly, they’re rarely even that strategic. Organizations reorg because priorities shift, leaders change, headcount fluctuates, and Conway’s Law keeps asserting itself. If you want the system to change shape, the org that builds it has to change shape first.

A reorg is just an organization updating its structure to match its current understanding of the problem. Sometimes that understanding is right. Sometimes the same boxes get redrawn eighteen months later. Either way, the org chart is a snapshot of a hypothesis, not a monument. Expecting it to be permanent is the actual mistake. Reorgs are the organizational equivalent of turning it off and back on again.

Why they feel so disruptive#

The disruption is real. But it’s also predictable, and predictable disruption is something you can design for.

Treat reorgs as a constant, not an exception#

This is the mindset shift that changed how I experienced reorgs: stop treating them as rare disasters and start treating them as baseline operating conditions. If you’ve been in tech for any length of time, a reorg every six-ish months is the weather. You don’t get angry at rain. You buy a raincoat. (share this quote)

Designing your career for that reality means investing in what survives an org-chart shuffle. Keep your relationships portable. Your network shouldn’t be coterminous with your reporting line, because the colleagues two teams over are your future teammates and references once the boxes get redrawn. Document your decisions somewhere durable; context that lives in one person’s head evaporates in a reorg, while context that lives at a URL survives. Working asynchronously and in the open is reorg insurance. And do work that’s legible on its own, because when your manager changes every year on average, your reputation can’t hang on any single person having seen your best work. Keep the receipts.

How to navigate a reorg#

When the announcement drops (usually on a Monday; I have the data):

Let the dust settle. The org chart announced on day one is rarely the org chart that exists a month later. Reorgs are announced at the altitude of VPs and refined at the altitude of teams. Don’t make big career decisions (or send spicy Slack messages) in week one.
Ask the questions that actually matter. Who do I report to? What does my team own now? What changed for users? Most of the anxious speculation that follows a reorg dissolves once those three are answered. The rest is noise.
Re-onboard yourself. A new team is a new job, even if your badge and laptop stay the same. Treat it that way: learn the team’s context before prescribing changes, go near, go far, and meet in the middle.
Reset with your new manager deliberately. Don’t wait for them to figure you out: that’s a six-month project you can compress into one good first one-on-one. Bring your brag doc. Share how you work best, what you’re driving, and what you need from them. Thirteen managers in, I can tell you the relationship you build in the first two weeks is the relationship you’ll have.
Keep showing your work. In moments of uncertainty, visibility matters even more. Leaders show their work, and reorgs are precisely when everyone (new manager, new skip, new peers) is trying to figure out who does what.

How to make the most of one#

Navigating a reorg is table stakes. The real opportunity is that reorgs are one of the few moments when an organization’s defaults become negotiable:

Reorgs reset narratives. Pigeonholed into a role you’ve outgrown? Your new manager has no priors. The story of who you are professionally gets re-told every reorg. Make sure you’re the one telling it.
Renegotiate your scope. Team charters get rewritten in the first few weeks after a shuffle, and nature abhors a vacuum. Show up with a proposal for what your role should be, and more often than not, you’ll get it. Clarity is a gift to a leader who’s drowning in ambiguity.
Shed the legacy cruft. Every team accumulates projects that persist purely through inertia. A reorg is organizational garbage collection, the rare moment you can ask “should we still be doing this?” and have “no” be an acceptable answer.
Compound your network. Every reorg deals you a new hand of colleagues, stakeholders, and adjacent teams. Thirteen years of shuffles meant I’d worked with (or near) half the company. That network outlasted every org chart that created it.
Be the calm one. When everyone else is doom-scrolling the new org chart,³ the person who’s level-headed, generous with context, and helping others find their footing is doing leadership, visibly, at exactly the moment leadership is paying attention.

The long view#

Across 25 reorgs, my manager changed, my team changed, my org changed, and my VP changed. But the things that actually determined my trajectory didn’t live on the org chart at all. My reputation persisted. My relationships persisted. The work, shipped, documented, linkable, persisted.

That’s where I’d tell you to invest. Not in any particular box or reporting line, but in the things no reorg can take from you. Get those right, and a reorg stops being a crisis and becomes what it actually is: a Monday. (share this quote)

The model’s parting gift was one final forecast: another reorg by early September, probably announced on a Monday. I have complete faith it will deliver. After all, look at the methodology:

Generated with 10,000 Monte Carlo simulations, bootstrap resampling, Weibull MLE, Kaplan-Meier survival analysis, CUSUM changepoint detection, Shannon entropy, Ljung-Box serial correlation testing, Poisson process goodness-of-fit, and a 6-model forecast ensemble. Because why not.

Reorgs happen. Plan accordingly.

“Like clockwork” is generous. The actual gaps ranged from six weeks to fifteen months, which is exactly why predicting the next one required increasingly heavy statistical machinery. The clock is real. It just has terrible build quality. ↩
The project began as a CSV with two columns and ended, several late nights later, as a statistical apparatus wildly disproportionate to the question it answered. Its README footer (reproduced in full at the end of this post, because it deserves to be) is the most honest line of documentation I’ve ever written. It’s open source now, in all its over-engineered glory. ↩
One faithful Hubber took coping to its logical conclusion and built a reorg playlist, stocked with such classics as “Changes,” “It’s the End of the World as We Know It,” “End of the Road,” “Another One Bites the Dust,” “Won’t Get Fooled Again,” and (my personal favorite) “Let It Go.” Reorg-driven development has a soundtrack now. ↩

Out now

There's a whole book's worth more where this came from.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

AI-first program management

ben@balter.com — Sun, 31 May 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

When I first wrote about the nine things a program manager does, I didn’t dwell on what the job actually feels like first thing on a Monday. The hardest part was always the scramble: a dozen threads that moved over the weekend, a risk or two that quietly materialized, and a critical deliverable whose scope someone changed in a comment buried three levels deep. All of it has to be synthesized into a coherent picture before the leadership sync, and the clock doesn’t care how many tabs you have open.

That scramble hasn’t gone away. But increasingly, I’m not doing it alone.

From async to AI-augmented#

The evolution makes sense in hindsight. I’ve argued that teams should default to async communication — written, durable, discoverable artifacts over synchronous meetings. That managers should use the same tools engineers use — issues, pull requests, project boards — to plan and track their own work. And most recently, that AI agents are extending the same patterns of transparency and code review that made open source successful.

If the shift from synchronous to async was about decoupling communication from presence, and managing like an engineer was about applying developer workflows to leadership, then AI-first program management is the next logical step: using AI to amplify the judgment, pattern recognition, and relationship work that makes program managers effective.

The through-line is the same principle I’ve been writing about for years: make work visible, make it durable, and reduce the friction between having an idea and acting on it. AI doesn’t change that philosophy so much as run it faster.

AI across the PM toolkit#

Each core PM responsibility shifts when AI enters the picture — and some don’t.

Communication, coordination, and facilitation#

Program managers are professional context-switchers. You spend your day translating between engineering teams, product managers, designers, and executives — each with different mental models and vocabulary.¹ It’s an O(n²) communication problem, and it only gets worse as the organization grows.

AI doesn’t eliminate that complexity, but it compresses the information-shuttling work. Hand an LLM a 200-message thread and it’ll hand back a paragraph. Feed it the engineering team’s “we’re blocked on a schema migration that requires a backward-compatible rollout strategy” and it’ll translate that into language an executive actually cares about. Drop in a wall of meeting notes and it’ll surface the three things that matter from the twenty that were discussed.

I’ve written about how we communicated at GitHub — optimizing for clarity, discoverability, and low-context readers. AI handles the mechanical work of drafting and reformatting for different audiences. The editorial choices — what to communicate, what to emphasize, when to pick up the phone instead — stay with you.

Capture and track work#

One of a PM’s most underappreciated responsibilities is ensuring that work doesn’t fall through the cracks. Every conversation, decision, and commitment needs to land somewhere trackable — usually an issue or a project board.

Point AI at a meeting transcript and it’ll auto-generate the issues. Point it at a month of Slack and it’ll surface the commitments that never made it into a tracker, flag the issues nobody’s touched in weeks, and notice when a project board has quietly drifted from reality. Think of it as a continuous reconciliation process — a linter for your program’s state, catching the gap between what people said they’d do and what the artifacts actually reflect.

This matters because the biggest risk in program management isn’t that something goes wrong. It’s that something goes wrong and nobody notices until it’s too late.

Risk identification and mitigation#

Speaking of risk — PMs are supposed to see around corners. In practice, that means reading a lot of threads, attending a lot of standups, and developing an intuition for when something feels off.

AI augments that intuition with pattern recognition at scale. It can analyze velocity trends across repositories, flag pull requests that have been open too long, identify dependencies that no human mapped, and surface cross-project risks that are invisible when you’re looking at one team’s board in isolation. I’ve called transparent collaboration the andon of knowledge work — pull the cord when something’s off. AI is an andon that monitors every cord at once, catching a staffing conflict between two programs before either PM realizes they’re competing for the same engineer’s time.

AI won’t replace the experienced PM’s gut feeling that “this one’s going to slip.” But it surfaces the signals earlier, giving you more time to act. The best risk management has always been about buying time.

Reporting up and across#

Nobody became a program manager because they love writing weekly status reports. And yet, clear upward reporting is one of the highest-leverage things a PM does. It’s how leadership knows where to pay attention and where to stay out of the way.

At GitHub, I built an internal tool called SnippetGPT that drafted these reports from a team’s activity for the week — commits, merged PRs, issue closures, comment threads. It rolled all of that up into a first draft aimed at engineering leaders. Instead of spending Friday afternoon assembling a narrative from memory and half-updated boards, I started from something that reflected what actually happened, then layered on interpretation and recommendations.

The key word there is start. An AI-generated status report is a first draft, not a finished product. The PM’s job is to add the “so what” — the strategic interpretation that turns a list of activities into insight. SnippetGPT gave me the what. I added the why it matters and the what to do about it. And once that draft existed, retargeting it for another audience — execs, a partner team, my own engineers — was nearly free: the same week’s activity, recut for whoever needed to read it.

Relationship management#

Program management is fundamentally a relationship business. When I first moved into the TPM role, I remember watching senior PMs set up “just wanted to say hello” meetings and dismissing it as socializing on company time — until I realized that’s exactly the point.² You make regular deposits to the social capital bank long before you need a withdrawal. AI doesn’t replace that. You can’t automate trust.

But it can help you maintain those relationships at scale: a nudge that you haven’t checked in with a particular stakeholder in two weeks, a bit of context surfaced before a meeting — “last time you spoke with this team, they raised concerns about the timeline for the API migration.” A first pass at a thoughtful reply to a tricky message when you’re running low on cognitive bandwidth at 4 PM on a Thursday.

The human work — building rapport, reading a room, knowing when someone’s frustrated versus when they’re genuinely blocked — stays firmly in the PM’s domain. AI just helps you show up more prepared and more responsive than you could be on your own.

Consensus and conflict resolution#

Driving consensus across teams with competing priorities is among the hardest things a PM does. It requires understanding not just each team’s position, but their interests — the underlying needs that drive those positions.

AI can help by synthesizing different viewpoints, drafting proposals that incorporate multiple perspectives, and suggesting compromises based on stated constraints. Need an RFC that reflects six teams’ input? AI can produce a first draft that no single person could assemble manually — but you still need to facilitate the conversation that turns a draft into a decision.

Where AI falls short is in reading the political dynamics. Understanding that Team A’s objection is really about being burned in a previous launch, or that a particular VP’s silence means something different than a junior engineer’s silence — that’s pattern recognition of a deeply human kind. No model is going to learn the org chart’s shadow topology from a prompt.

What doesn’t change#

It would be easy to read all of this and conclude that AI is about to make program managers obsolete. It won’t.

The responsibilities haven’t changed. What’s shifted is the mix of the day: less time processing information, more time on judgment. AI reads the forty-message thread; you still decide whether the disagreement buried two-thirds of the way down needs a meeting or just a quiet word with the two people in it.

The things AI can’t do are the parts that were always the hard part: reading a room, building trust over months, knowing when to push and when to back off, making the call when the data is ambiguous and someone still has to own the outcome. Those get more valuable as AI absorbs the routine work. When everyone has access to the same AI tools, the differentiator is the human wielding them. (share this quote)

What changes for PMs#

That said, AI-first program management does require new muscles — or at least, new applications of existing ones. Four stand out:

Prompt craft is just requirements-writing. Ask an LLM to “summarize the launch thread” and you’ll get mush. Ask it to “pull out every unresolved decision and its owner, and flag anything blocked on another team” and you’ll get something you can act on before the sync. It’s garbage in, garbage out, a principle as old as punch cards, now pointed at prompts. The years you spent writing crisp issue descriptions and acceptance criteria were the training.

Knowing when not to reach for it. The message to the stakeholder whose project just got cut, the escalation where two directors are fighting a proxy war over headcount, the report who’s having a rough week—hand any of those to an AI and you’ll ship something correct and tone-deaf. Which conversations are yours alone is a skill, and you mostly learn it by getting it wrong once.

Verification, because AI fails confidently. It’ll summarize a forty-message thread and drop the one comment where an engineer admitted the date was slipping. It’ll draft a status report that’s 90% right and 10% quietly wrong. Your job moves from writing the draft to catching that 10% before it ships—which means knowing the ground truth well enough to see where the model smoothed it over.

Fluency is table stakes. Nobody lists “can use a project board” on a résumé anymore. Working with AI assistants is on the same curve: a novelty this year, an assumption the next, as unremarkable as Slack or email or GitHub Issues.

The judgment is still yours#

The last big launch I ran, every dashboard was green the Friday before ship: PRs merged, tests passing, no open blockers, and SnippetGPT’s rollup said exactly that. What the board didn’t show was that one engineer had gone quiet in the launch channel three days running—terse in a way he normally wasn’t—and the security reviewer had signed off with a single “lgtm, mostly.” No tool reads “mostly” as anything but approval. I read it as a person who had found something and hadn’t decided how much it mattered yet. We held the launch a week, and the hedge turned out to be an auth edge case that would have paged us at 2 AM on day one.

No model was going to catch that. It would have read the same green board I did. The job was never assembling the status—AI can do that now—it’s knowing which green is actually green, and who to call when it isn’t.

The shift to async made program management more intentional. Managing like an engineer made it more transparent. AI makes the same hours count for more. Each of those shifts moved routine work off the PM’s plate and left the judgment exactly where it was.

Much of the job is a long tail of grab-bag work that never fits a clean category — writing the missing spec, scheduling the meeting nobody wants to own, reformatting a spreadsheet at 9 PM because a VP asked for a different view of the data. AI is exceptional at exactly this kind of mundane-but-necessary task, and it’s the easiest place to start. If you’re a PM wondering where to begin, pick the task that consumes the most time but requires the least judgment — status report assembly, meeting note cleanup, stakeholder update drafts — and hand it to an AI. You’ll free up hours for the work that actually drew you to the role: solving hard problems with smart people across organizational boundaries.

Tally up the number of distinct audiences a PM communicates with in a single week and the answer is genuinely depressing. Every additional team or stakeholder doesn’t just add one more communication channel — it adds one for every stakeholder you already had. This is why PMs’ calendars look the way they do. ↩
As much as I might like them to be, human-to-human requests are unlike server-to-server requests. A properly authenticated request from a never-before-seen client is less likely to be fulfilled, or fulfilled in a timely manner, even if it’s facially valid. Invest in the relationship before you need the favor. ↩

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

How to one-on-one

ben@balter.com — Mon, 27 Apr 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

It’s Thursday afternoon. Your direct report sits down and reads from a list: “Closed three bugs, reviewed two PRs, started the migration doc.” You nod. They nod. Thirty minutes pass without either of you saying anything that couldn’t have been a comment on an issue.

Most 1:1s fail in one of three ways:

The most common: spending your team’s only protected synchronous time on information that belongs in writing.
The second: sugarcoating hard feedback until nobody walks away clear on what actually needs to change.
The third is quieter: the 1:1 that keeps getting canceled because “something came up,” until the relationship slowly starves.

What belongs in a 1:1#

Great 1:1s focus on topics that only work synchronously. Five keep coming up:

Career growth. “Should I chase the tech lead role or move toward management?” isn’t a question you resolve in an issue comment. It needs back-and-forth, and half the signal is in what your report doesn’t say out loud when you name each path.
Coaching. A report is stuck on how to push back on a staff engineer who keeps silently rewriting their PRs. There’s no doc to link them to. They need to talk it through with someone who has the context and no stake in the outcome.
Feedback. “Your design review comments are landing as combative” reads like an ambush in Slack and like a favor across a table. The pause where they react, and your chance to say “that came out wrong, here’s what I meant,” is the entire point.
Human connection. “How are you actually doing?” And then sitting through the silence that follows. Remote work strips out the hallway read on whether someone’s thriving or quietly burning out. The 1:1 is where you get it back.
Clearing the air. The passive-aggressive thread that’s been simmering all week gets defused in four minutes of talking, or festers for another month in writing. Pick up the phone.

What doesn’t belong: status updates, information transfer, and approval requests. If you’re listing what you shipped last week, you’re wasting the meeting. (share this quote) Your manager should see your work before the 1:1, not hear about it during. Approvals create bottlenecks. Ask async. Information sharing belongs in a doc sent beforehand. Use synchronous time to discuss implications, not convey facts.

How to prepare#

Great 1:1s start before the meeting does.

Keep a running shared agenda (a Google Doc, a GitHub issue, whatever works) where both parties add topics throughout the week. When something comes up worth discussing, add it immediately instead of trying to remember later.

Add context to each item. Don’t just write “career growth.” Write “I’ve been thinking about whether to pursue the tech lead path or people management, and I’d like to talk through the tradeoffs.” The more context upfront, the more productive the conversation. Prioritize ruthlessly. You won’t cover everything every week, and if something keeps rolling without getting discussed, that tells you something about its actual importance.

A good test of your preparation: could you cancel the meeting without losing anything? (share this quote) If yes, you either don’t have enough prepared or you’re covering topics better handled async.

How to run one#

Start with the human, not the agenda. Take a few minutes to check in personally. This isn’t small talk. It’s the relationship that makes hard conversations possible later.

Ask questions more than you give answers. For managers, your job isn’t to solve every problem. It’s to help your report think through problems themselves. “What options are you considering?” is often more useful than “Here’s what you should do.” For ICs, don’t just wait to be told what to do. Challenge assumptions and push back.

Follow the agenda, but hold it loosely. If a topic opens up a more important conversation, follow it. The rest can wait.

Make space for what’s unsaid. The most important topics often aren’t on the agenda because they’re hard to articulate or feel risky to raise. Make it safe by raising difficult topics yourself and responding non-defensively when others do.

End with clear next steps. What actions came out of this? Who’s doing what by when? Document them somewhere durable so they don’t get lost. Leaders who show their work in shared docs make this easy. The same transparency that helps distributed teams function day-to-day makes 1:1 follow-through automatic.

Skip-levels: why they matter#

Skip-level 1:1s, regular conversations with your manager’s manager, build rapport and broader perspective. They’re typically less frequent (monthly or quarterly), but they matter for career visibility and organizational context. They give senior leaders unfiltered signal about how the team is actually doing, and they give ICs a line of sight into strategy they wouldn’t otherwise have.

Anti-patterns to avoid#

The ghost meeting. Neither party prepares, there’s no agenda, and you spend thirty minutes in a conversational holding pattern. If you have nothing to discuss, either something is going well or something is going unaddressed. Figure out which.
The cancellation cascade. 1:1s keep getting canceled because “something came up.” That signals the relationship isn’t a priority. Protect the time, especially for remote relationships where it’s harder to connect informally.
The manager monologue. The manager talks the whole time, sharing information, giving advice, or thinking out loud. 1:1s should be conversations, not presentations.
The reverse 1:1. The entire meeting becomes the report briefing the manager on the work. If your report is educating you for thirty minutes, you owe them a different format, not a recurring appointment.

The real test#

Your 1:1s are a microcosm of how you lead. Shared agendas, documented outcomes, async preparation: every practice that makes a 1:1 great is the same practice that makes a distributed team work. If you manage like an engineer, you already have the instincts: treat the meeting like a system, instrument it, and iterate.

Get the 1:1 right and the rest follows.

Out now

This post is adapted from my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

The brag doc

ben@balter.com — Mon, 27 Apr 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

Here’s the best career advice I ever received as a product manager: “product-manage your own career.” I wish I’d internalized it sooner. Early in my career, I stayed quiet and did good work, assuming the right people would notice. Spoiler: they didn’t, not because the work wasn’t good, but because nobody else was tracking it.

Treat yourself as a product. What are your features? What are your bugs? What does your roadmap look like? And critically: who’s keeping the changelog?

Nobody’s keeping score for you#

Unless you’re a professional athlete, nobody’s compiling your stats. Your manager has their own deliverables, their own manager to impress, and a dozen other direct reports. They aren’t maintaining a highlight reel of your career. That’s your job.

In remote organizations, this problem compounds. There’s no hallway reputation, no casual office face time, no lunch with the VP where you happen to mention your project. If people don’t see your work in pull requests, issues, or public discussions, they don’t know you exist. Working in the open creates a natural paper trail: public pull requests, documented decisions, visible contributions. But that trail only matters if you curate it.

The ship log#

Maintain a “ship log.” Call it a “brag doc,” “hype doc,” “smile file,” whatever gets you to actually use it. Each time you hit a milestone, record it with its impact and any relevant metrics. Async work hands you a head start: your contributions are already timestamped and linkable.

Your ship log combats impostor syndrome, makes annual self-assessments trivially easy to write, and keeps your professional profiles current. If you didn’t log it, it didn’t happen. (share this quote)

The format doesn’t matter: a Google Doc, Apple Notes, a text file in your home directory. What matters is that it’s easy to update and always within reach. Every Friday, spend five minutes adding bullets: what you shipped, what you unblocked, what decisions you influenced.

What makes a good entry#

Effective ship log entries are:

Specific and linked. “Improved documentation” is vague. “Rewrote the onboarding docs, resulting in 40% fewer support tickets from new hires ([link to the issue])” is evidence.
Impact-focused. List outcomes, not activities. “Attended twelve planning meetings” says nothing. “Proposed the architecture that shipped to production” tells a story.
Continuous. Don’t wait until review season. Update weekly, while the details are fresh.
Shareable. Your log isn’t a secret diary. Share highlights with your manager regularly. The best time to make your case for promotion is months before the conversation happens.

Don’t limit yourself to completed deliverables. Screenshot the email where a stakeholder said your proposal changed their thinking. Note the meeting where your question reframed the entire discussion. Record the mentoring conversation that helped a junior engineer get unstuck. These qualitative moments are often more compelling in a promotion case than a list of closed tickets.

Climbing Cringe Mountain#

Yes, maintaining a brag doc feels awkward. There’s a reason people call it “climbing Cringe Mountain.”

Fighting recency bias#

Here’s the real killer: recency bias. Your manager (and you) will tend to remember only the last few weeks when evaluation season arrives. That critical project you shipped in February? Without a record, it might as well not have happened by December.

A ship log is your defense. When it’s time for self-assessments, you open the doc and the year’s work is right there: specific, linked, and impact-focused. No scrambling, no guessing, no accidental amnesia about Q1.

Make it a habit#

A brag doc only works if you actually maintain it. Some practical tips:

Set a weekly reminder. Friday afternoon, five minutes. What did you ship? What did you unblock? What decisions did you influence?
Ship something visible every week. It doesn’t have to be a major feature. Fixing a bug, improving documentation, or sharing a design sketch counts. Make shipping a habit, not an event.
Share progress within a day or two. If you’ve been working on something for more than a day or two without sharing any progress, you’re probably holding on too long. Unshipped work is invisible work.
Feed your self-assessments. When review season comes, your log is your self-assessment draft. Copy, paste, polish.
Build your promotion packet early. The best promotion cases aren’t written in a weekend. They’re assembled over months from a well-maintained log.

Nobody else will manage your career. Your company manages your role. You manage your trajectory. (share this quote) Start the doc today. Future you will be grateful.

Out now

There's a whole book's worth more where this came from.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

No agenda, no meeting

ben@balter.com — Mon, 06 Apr 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

You get the invite. No description. No agenda. No attached document. Just a title like “Quick sync” and a 30-minute calendar hold. You accept it anyway, because what else are you going to do — decline a meeting with your skip-level?

I’ve written before about how meetings should be a point of escalation, not a starting point. But the agenda-free meeting is an even more fundamental failure mode: it’s a meeting that hasn’t even bothered to justify its own existence.

So I made a site about it: noagendanomeeting.net.

The cost of no agenda#

A meeting without an agenda is like calling a function without documentation — sure, it might do what you expect, but you’re forcing every caller to read the implementation to find out. Meetings without agendas force everyone to context-switch twice: once to figure out what it’s about, and again in the meeting itself when they arrive unprepared.

The average knowledge worker already spends 40% of their workweek in meetings. Without clear goals, those meetings drift, no decisions get made, and everyone leaves wondering if that could’ve been an email. (It could’ve.)

The thesis#

The site’s core argument: writing scales; meetings don’t. Before you send that invite, ask yourself: can this start as a document instead?

If the answer is yes — and it almost always is — write first, meet second. If you do need a meeting, include an agenda, attach a read-ahead, and state the decision you’re trying to make. This isn’t radical advice. It’s basic async-first communication hygiene.

What to do about it#

Next time you get a meeting invite without an agenda, try something wild: decline it. Or better yet, reply asking for one. You can even send them the link — noagendanomeeting.net is a lot more diplomatic than “I’m not attending your agenda-free ambush.”

If you manage like an engineer, you already know that undefined inputs produce undefined outputs. Meetings are no different. Define the problem before you schedule the standup. (share this quote)

Check it out at noagendanomeeting.net, and the next time someone sends you a mystery meeting, you’ll know exactly what link to send back.

Out now

There's a whole book's worth more where this came from.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Agentic workflows and the future of code

ben@balter.com — Wed, 18 Mar 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

A number of years ago, I wrote about how pull requests are a form of documentation — not just a code review mechanism, but a persistent record of why a change was made, what alternatives were considered, and how the team arrived at a decision. At the time, I was thinking about human collaboration. I didn’t anticipate that the same argument would soon apply to how we collaborate with AI.

Agentic workflows — where AI agents autonomously write code, run tests, fix bugs, and open pull requests — are quickly moving from demo to daily practice. What strikes me most about this shift isn’t the technology itself, but how naturally it maps to patterns we’ve already built. Pull requests. Code review. Transparent decision-making. Showing your work. The interface for human-AI collaboration was hiding in plain sight all along.

From autocomplete to autonomy#

Most developers are already familiar with AI-assisted coding through tools like GitHub Copilot, which suggests code completions as you type. That’s useful, but it’s fundamentally still you driving — the AI is a passenger offering directions. Agentic development flips that relationship. You describe what needs to happen (“fix this bug”, “add pagination to this API endpoint”, “update these dependencies”), and an AI agent goes off and does the work: reading the codebase, writing code, running tests, iterating on failures, and eventually opening a pull request for your review.

Think of it less like a smarter autocomplete and more like assigning a task to a capable but junior developer. You provide context and direction. They do the implementation. You review the result.

This isn’t hypothetical. GitHub Copilot’s coding agent can already take a GitHub issue, spin up a cloud development environment, write the code, validate it against your CI pipeline, and open a PR — all without a human touching a keyboard. The pull request becomes the handoff point, the place where human judgment re-enters the picture.

Building on what already works#

Here’s why I find agentic development so compelling: it doesn’t require inventing new collaboration patterns. It builds directly on the ones we already have.

I’ve spent a good chunk of my career at GitHub advocating for practices that, at the time, were about improving human collaboration:

Pull requests as documentation — Every change should come with context, rationale, and a discussion trail. I wrote about this in Pull requests are a form of documentation, and it’s even more relevant when the author is an AI agent that can’t casually explain its reasoning over coffee.
Code review as quality control — A second set of eyes on every change catches mistakes and spreads knowledge across the team.
Transparency and visibility — Making work visible means anyone can see what’s happening, why, and by whom — what I’ve called the “andon cord” of knowledge work.
Automation as a force multiplier — CI/CD pipelines, linters, automated tests — we’ve been offloading mechanical tasks to machines for years. AI agents are the next step in that trajectory.

These practices weren’t designed with AI in mind, but they created the exact infrastructure agents need to participate in software development. An agent can open a pull request because pull requests already exist as a structured way to propose, discuss, and review changes. An agent’s work can be reviewed because code review is already how we verify quality. An agent’s reasoning can be traced because we already expect changes to come with explanations.

Teams that have invested in strong PR conventions, thorough code review, comprehensive test suites, and reliable CI pipelines will find the transition to agentic development surprisingly smooth. Teams that haven’t? They’ll struggle — not because the AI is hard to use, but because they lack the collaboration infrastructure that makes it effective.

Why pull requests are the perfect interface#

If you had to design an interface for human-AI collaboration from scratch, you’d probably end up with something that looks a lot like a pull request.

A pull request provides:

A clear proposal — Here’s what I want to change and why
A discussion thread — Questions, feedback, and iteration
Automated checks — Tests, linting, and CI verify the change works before a human even looks at it
A review mechanism — A human approves (or requests changes) before anything ships
An audit trail — A permanent record of what changed, when, and why

That’s everything you need for effective oversight. The AI agent does the implementation and opens the PR. GitHub Actions runs the automated checks. You review the diff, read the description, ask questions in comments, and approve or request changes — the same process you’d follow with a human contributor you’ve never met before.

This isn’t a coincidence. Pull requests evolved as the open source community’s answer to a fundamental challenge: how do you accept contributions from people you don’t fully trust, at scale, while maintaining quality? That’s a problem we solved decades ago with code review, CI, and transparent discussion. AI agents are the latest class of contributors benefiting from that infrastructure.

A shift from writing to reviewing#

One of the more interesting implications of agentic development is how it changes what developers actually spend their time doing. When an AI agent handles the initial implementation, your role shifts from writing every line of code to something closer to a tech lead: providing context, setting direction, and reviewing output.

I wrote about a similar dynamic in Manage like an engineer — the idea that good management applies many of the same principles as good engineering. Working with an AI agent extends that analogy further. It’s like managing a junior developer who’s incredibly fast, never gets tired, and has read every Stack Overflow answer — but who still needs guidance, context, and oversight to produce work that fits your team’s standards.

This means the skills that matter shift too:

Writing clear problem descriptions becomes more valuable than writing boilerplate code from scratch
Code review skills move from “nice to have” to essential daily practice
System-level thinking — understanding architecture, trade-offs, and context — matters more than syntax fluency
Judgment — knowing when to accept, reject, or redirect the agent’s output — becomes critical

None of this makes developers less important. If anything, it makes experienced developers more important, because the skills that are hardest to automate — architectural judgment, product intuition, understanding user needs — are exactly the skills senior engineers contribute.

Trust but verify#

I want to be direct about something: the need for human oversight doesn’t go away as AI agents get better. It arguably increases.

When a colleague opens a pull request, you bring assumptions to the review. You know they understand the team’s conventions. You know they’ve considered the user’s perspective. You know they’ve thought about edge cases, even if they missed some. With an AI agent, you can’t make those assumptions yet. The code might be syntactically correct and pass all tests while still missing important context about why your team chose a particular pattern, or what a product manager actually meant by “improve the onboarding flow.”

This is why practices like transparent collaboration and consistently shipping great features matter more than ever. Good process isn’t bureaucracy — it’s a safety net. When you have comprehensive tests, reliable CI, thorough code review, and clear coding standards, you can confidently accept contributions from any source, human or AI, because the process catches problems regardless of who introduced them.¹

A few principles worth keeping in mind:

Review AI-generated code with the same rigor you’d apply to any external contribution. Don’t let the novelty of AI make you either too skeptical or too trusting.
Invest in your test suite. Automated tests are the single best defense against subtle bugs, whether introduced by a human at 2 AM or an AI agent at 2 PM.
Keep a human in the loop for anything that touches users directly. AI agents are great at mechanical tasks, but product decisions still need human judgment.
Treat AI-generated PRs as a learning opportunity. Reviewing them helps you understand what the agent does well and where it consistently falls short.

Making agentic development work for your team#

If you’re considering adopting agentic practices — and at this point, you probably should be — here’s where I’d start:

Shore up your fundamentals first. Descriptive PR templates, a comprehensive test suite, reliable CI, and clear contribution guidelines aren’t just nice to haves anymore — they’re prerequisites. An AI agent can only be as effective as the development infrastructure it operates within.
Start with well-scoped tasks. Bugfixes, dependency updates, boilerplate scaffolding, test coverage improvements — these are ideal entry points. Save the complex architectural decisions for when you’ve built confidence in the approach.
Write better issues. The quality of an agent’s output is directly proportional to the quality of its input. Invest time in clear, detailed issue descriptions with acceptance criteria, context, and pointers to relevant code. This habit, by the way, improves human contributions too.
Iterate on your review process. Pay attention to what the AI gets right and where it misses the mark. Use that information to refine your prompts, your contribution guidelines, and your review checklists.
Don’t lower your standards. It’s tempting to merge AI-generated code faster because it “feels” different from a human’s PR. Resist that impulse. Your review process exists for a reason.

What comes next#

I’ve been at GitHub long enough to see several waves of tooling transform how developers work — from hosted version control to pull request-driven collaboration to CI/CD to Copilot’s autocomplete. Agentic AI feels like a natural continuation of that trajectory, not a departure from it.

What excites me most isn’t the AI itself but the validation of practices the open source community has championed for years. Why open source? Because transparency, collaboration, and peer review produce better outcomes than closed, opaque processes. Agentic AI doesn’t change that equation — it strengthens it. The pull request, the code review, the public discussion trail — these aren’t relics of a pre-AI era. They’re the foundation of the AI-augmented one.

The developers and teams who thrive won’t be the ones who write the most code. They’ll be the ones who provide the best context, ask the sharpest questions, and maintain the highest standards for what gets shipped — regardless of who or what wrote it.

This is one of those cases where doing the right thing for your human contributors and doing the right thing for AI agents turn out to be the same investment. Funny how that works. ↩

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Thirteen years remote at GitHub: what works

ben@balter.com — Wed, 04 Mar 2026 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

We do so many aspects of the workday just because it’s how things have been done since the dawn of the Industrial Revolution. Nobody’s stopped to rethink these processes with modern technology. That perspective shaped how I recognized what GitHub had already accomplished.

A company that rethought the defaults#

When I joined GitHub in 2013, I found a company that had fundamentally rethought those assumptions about work—it was a remote-first company with no managers and employees spread across the globe (for most of GitHub’s history, 60–75% of employees were remote—today GitHub is 100% remote). This was unusual for startups, let alone large corporations. GitHub was dogmatic about “optimizing for developer happiness,” ensuring the internal development experience was as smooth and integrated as possible.

Inspired by open-source workflows—the same workflows many GitHub developers grew up with—nearly everything was async. Between GitHub issues, chat, and our trusty robot sidekick Hubot, GitHub was practicing DevOps before it became mainstream. Remote work wasn’t just possible; it was genuinely enjoyable, embedded as a core part of our culture. Put simply, we used GitHub to build GitHub.

Using GitHub to build GitHub#

GitHub’s development workflow wasn’t born from any formal methodology—it grew out of open-source culture. There were no mandatory daily standups, no sprint planning ceremonies, no fixed-cadence retrospectives. If you had to pin a label on it, the approach looked far more like Kanban’s continuous flow than Scrum’s time-boxed sprints: work moved through visible queues, got reviewed asynchronously, and shipped when it was ready.

Not all methodologies translate equally well to open and async work. Flow-based approaches—where work is visible on a board, review happens asynchronously, and delivery is continuous—map naturally onto distributed teams. Ceremony-heavy frameworks that depend on everyone being in the same room (or the same time zone) at the same time fight against the grain. The goal isn’t to abandon structure, but to choose structure that makes work visible rather than synchronous.¹

Open-source workflows for everything#

This extended to non-code workflows as well. GitHub Issues, Pull Requests, and Markdown were used to manage internal policies, legal matters, HR, and Sales. Need a contract reviewed? Open an issue. Want to propose a change to the vacation policy? Submit a pull request. How you work is just as important as what you work on, so why not use the best tools available?

The choice of Markdown wasn’t arbitrary—it uses simple characters you already know (# for headings, - for bullets, ** for bold) to format plain text that’s readable even without rendering. Unlike emailing Word documents back and forth with revision marks and conflicting versions, Markdown files play nicely with version control and render beautifully in most modern tools. This eliminated the perennial “which version is current?” problem and made collaborative editing genuinely async. When your HR policy lives in a Markdown file with a complete change history, everyone can see not just what the policy is, but why it changed and who advocated for it.²

A hub, not a headquarters#

GitHub had a physical office in San Francisco, but it was more hub than requirement. The office served as a space for meetups, events, and coworking rather than a mandatory 9-to-5 workspace. Hubbers (GitHub employees) were free to work whenever and wherever they were most productive—whether at 3 AM or as digital nomads. This flexibility stood in stark contrast to the traditional office culture of the time.

Despite being remote, GitHub valued in-person interactions. The company hosted an annual “summit” where all employees gathered for a week of talks and coworking, as well as smaller team “mini-summits” for planning and relationship-building. Even GitHub HQ was optimized for remote work, featuring open “cafés” for serendipitous interactions and advanced streaming setups for remote participation in all-hands meetings.

Early on, GitHub had “Hack Houses” where cross-functional teams would meet up in person for a week to ship a complex or high-profile project. We also had “Destinations” where employees could work for extended periods in shared houses in different locations around the world. These didn’t scale as we grew, but remain a powerful tool for smaller teams or companies to build relationships and ship work together.

Intentionality over proximity#

The physical space strategy reflected a deeper truth about remote work: what happens by accident in an office must be designed deliberately when distributed. You can’t rely on overhearing a conversation that sparks an idea or bumping into someone at the coffee machine who has exactly the context you need. These moments can still happen—they just require intentional creation rather than convenient proximity.

Remote teams often worry about losing the “water cooler” moments—those unplanned hallway conversations that spark unexpected ideas. Create digital equivalents: optional social channels, virtual coffee roulettes, or open-ended team threads. The serendipity doesn’t have to disappear; it just needs to be intentionally designed rather than left to physical proximity.

You’d think remote work would weaken company culture. The opposite was true. Remote work forced us to be intentional about communication, documentation, decision-making, and relationship-building. This intentionality strengthened GitHub’s culture, enabling it to scale from a small startup to a large company without losing its unique identity, even after its acquisition by Microsoft.

The pursuit of an ideal#

Over the years, GitHub practiced many of these principles—imperfectly and not always at once. It’s a story of pursuing an ideal while occasionally falling short. Even so, GitHub remains the closest I’ve seen to a company getting remote and distributed work “right,” which is why so many former Hubbers return after seeing how others do it.

What thirteen years taught me#

The patterns that emerged from a decade-plus of distributed experimentation—working in the open, defaulting to async, documenting decisions, making work visible—aren’t just GitHub quirks. They’re repeatable practices that any team can adopt, regardless of industry or company size.

GitHub’s remote work evolution shows that distributed collaboration isn’t just possible—it can be a competitive advantage. But success requires more than tools and good intentions. It requires a fundamental shift in how we think about work, communication, and collaboration. If you’re leading a distributed team, you have to invest in codifying practices, building shared context, and maintaining the cultural elements that made remote work successful when you were smaller. What happened organically at 50 people requires deliberate effort at 500. (share this quote) If you’re an individual contributor, the practices that work at scale are exactly the habits worth building now—clear documentation, async-first communication, transparent collaboration. These remote work skills are transferable to any organization and compound over time.

DevOps breaks down the wall between “people who write code” and “people who deploy it” by making both responsibilities visible and shared. One implementation—ChatOps—puts deployment (and cultural) commands in chat where everyone can see them, creating a natural audit trail and enabling asynchronous collaboration. ↩
Markdown has since become the lingua franca of AI. LLMs natively read and generate Markdown, and its lightweight syntax often uses fewer characters (and typically fewer tokens) than HTML or rich text formats, making every AI interaction more efficient. A format chosen for human collaboration turned out to be AI-native too. ↩

Out now

This post is adapted from my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

How to run LanguageTool on macOS

ben@balter.com — Thu, 30 Jan 2025 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

You may be familiar with grammar checking tools like Grammarly,¹ but if you’re privacy-conscious like me, you likely don’t want to send everything you type to a third-party service (or may be prohibited from doing so by your employer). Enter LanguageTool, a free and open-source grammar, style, and spell checker that can be run locally on your machine, so nothing you type ever leaves your computer (share this quote). LanguageTool can be used with your browser, with VS Code,² and with Slack and other common applications. For those looking to run LanguageTool like this, I’ve tried a number of ways, and here’s the easiest:

Set up the local server#

First you need to install the backend server, which is a Java application. You could do this manually or via Docker (trust me, I tried both with varying levels of success), but I recommend letting Homebrew do the heavy lifting for you.³ Homebrew creates its own languagetool-server executable that wraps the LanguageTool jar around the Homebrew-maintained Java runtime, saving you from having to manage a Java environment yourself. In theory, it “just works”. Here’s how to install and run it:

brew install languagetool
brew services start languagetool

This will install the LanguageTool server and set it to start automatically on boot as a Homebrew-managed service. Once you have the server running, you can use LanguageTool in your browser, in Slack, VS Code, etc. Read on for how to set up each (you can pick and choose once you’ve installed the server).

Note: If you’d like to test that the server is running at this point, you can run curl --data "language=en-US&text=a simple test" http://localhost:8081/v2/check.

One potential gotcha#

If you previously installed the languagetool cask,⁴ or accidentally installed it first, installing the non-cask version will likely fail to set up the backend service, due to the namespace conflict. The install command itself won’t fail, but you’ll see a “missing path” error in the installation output and the service will not be running. If so, here’s how to fix it:

brew uninstall languagetool --cask
brew reinstall languagetool
brew services start languagetool
Optionally reinstall the frontend (see below)

LanguageTool in your browser (Chrome, Edge, Firefox)#

LanguageTool works great in your browser for any text box, Google Doc, GitHub issue, etc. Here’s how to set it up:

Install the LanguageTool extension for your browser - Chrome, Edge, Firefox
In the extension settings, set the “API Server URL” to “Local server”.

That last step is important because the extension defaults to using the public LanguageTool server, which is not the one you just installed.

LanguageTool in Slack and other common work applications#

LanguageTool also has a macOS-native frontend that provides support for Slack, Mail, Word, and other common work applications. Here’s how to install it:

brew install languagetool --cask
Launch the app from the Applications folder
Open the LanguageTool settings via the menubar icon (LT icon > Gear icon > Settings)
Under “Advanced”, set the “API Server URL” to “Local server” (again, otherwise it will default to the public server)
Under “Active apps”, enable LanguageTool for Slack, etc.

LanguageTool in VS Code#

Install the extension.
It just works!

LanguageTool in Safari#

Safari does not allow extensions to make calls from HTTPS pages to HTTP endpoints (the local server), meaning before we can use the Safari LanguageTool extension, we’ll need to set up an HTTPS proxy so that it will work on HTTPS websites. Here’s an easy way to do that:

brew install caddy
Create a /opt/homebrew/etc/Caddyfile file with the following contents:
```
localhost:8082
reverse_proxy :8081
```
brew services start caddy. Note: You will be asked to sudo as Caddy creates a locally trusted certificate.
Install the Safari extension
In the Safari extension, for “API Server URL” choose “Other server” and enter https://localhost:8082/v2.

This will set up a reverse proxy that listens on port 8082 and forwards requests to the local LanguageTool server. If you’d like to test that the server and proxy are running, you can run curl --data "language=en-US&text=a simple test" https://localhost:8082/v2/check.

N-grams#

As a bonus, you can set up n-gram data sets to improve LanguageTool’s ability to detect errors with words that are often confused:

LanguageTool can make use of large n-gram data sets to detect errors with words that are often confused, like their and there.

It’s a large download, but it’s worth it if you have the space and are going to be using LanguageTool a lot. Here’s how to set it up:

Download the n-gram dataset(s) for your language(s) onto your local machine and unzip them into a local n-grams directory. I recommend ~/ngrams, but you can install it anywhere. (Note: the data is language specific, so unzip the download to, e.g., ~/ngrams/en).
Edit /opt/homebrew/etc/languagetool/server.properties, adding languageModel=/Users/benbalter/ngrams, replacing the path to the absolute path of where you downloaded and unzipped the n-gram data.
Restart the service: brew services restart languagetool

If you did it correctly, again, it should “just work”, but if you want to confirm, you should see a message in the logs that says INFO: Using n-gram data from /Users/benbalter/ngrams (or whatever path you used).

Troubleshooting#

By default, LanguageTool logs live in: /opt/homebrew/var/log/languagetool/languagetool-server.log and Caddy logs live in: /opt/homebrew/var/log/caddy.log. If you want to see if LanguageTool is running, you can use brew services list, or try one of the curl methods mentioned earlier.

Taking it a step further#

If you really want to make sure what you type doesn’t traverse the internet, you can modify your hosts file or use another method (like firewall rules or Little Snitch) to block the public LanguageTool server (api.languagetool.org) at the network level. This way, if you accidentally forget to set the “API Server URL” to “Local server” in one of the clients, the request will fail, and you’ll know that the client is not using the local server.

Conclusion#

That’s it! You now have a powerful, privacy-respecting grammar checker that you can use in your browser, in Slack, in VS Code, and in other common work applications. Happy writing!

Nothing against Grammarly. It’s a great product. I prefer to use open source tools whenever I can. ↩
I used the VS Code extension to write this post, so I really hope there aren’t any typos. ↩
If you’re not familiar with Homebrew, it’s a macOS package manager that makes it easy to install, manage, and update command-line software. If you don’t have it installed, you can do so by running the following command: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)". ↩
The non-cask version is the backend Java server. The cask version (by the same name) is the macOS frontend that provides a menubar icon and settings UI. ↩

Out now

Liked this post? It's now a book.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Silencing dissent isn't crisis management

ben@balter.com — Mon, 08 Jan 2024 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

Every seasoned leader I’ve worked with has had to make an unpopular or controversial decision. It’s one of the hallmarks of good leadership. But almost as important as the decision itself, is how you engage with your team following the decision.

It’s understandable. You spend days, weeks, maybe months agonizing over every detail, every pro and con, every possible outcome. You’ve done your due diligence, and you’ve made the best decision you can given the situation. You’re confident in your decision, and you’re ready to move forward. Then comes the inevitable push back from your team. They have questions, concerns, and objections. They’re not happy with the decision, and they’re not shy about letting you know.

It’s easy to dismiss that negativity as ignorant, personal, or a vocal minority (“you can’t please everyone”), after all, they have a fraction of the perspective you have as a leader. You might seek to “control the narrative”, by dismissing such voices as inviting negativity, undermining your authority, or asking questions that you’ve already answered, thinking it’s unproductive to further discuss a decision you know is final. Those are all understandable and human reactions.

“Controlling the narrative” is counterproductive#

Attempting to “control the narrative” by silencing dissent is not only ineffective, it’s also counterproductive:

It erodes psychological safety - When you shut down the conversation, you send a message that you don’t value the input, the perspective, or the feelings of those affected by your decision. You also signal that you have something to hide, or that you’re not confident in your own reasoning, further eroding trust.
It invites negativity - When you ignore the questions, you don’t make them go away. You just push them underground, where they fester and grow. People will start to speculate, gossip, and complain. They will feel resentful, frustrated, and alienated. They will look for ways to resist, sabotage, or undermine your decision.
It stifles learning - When you avoid the scrutiny, you miss an opportunity to “show your work” and teach through action. An organization’s culture and values are comprised of the underlying assumptions that its members use to make decisions. When decisions are transparent, you offer opportunities for the next generation of leaders to learn and grow through passive observation and lightweight participation.

“Caremad” is a good thing#

Like your own reaction, your team’s reaction is equally human, and I’d argue, actually a good thing.¹ It means they’re engaged. It means they care. While you’re ready to move on, they just got the news, and they’re still processing. The difference between good leaders and great leaders is in the follow through. Specifically, in their willingness to engage in the emotional labor of helping their team figure out how to move forward, together.

That dissent isn’t disengagement or obstructionism as it may be easy to misread. Quite the opposite. They’re likely “caremad”² - they’re upset because they care about ensuring the best possible outcomes and are trying to figure out how to do that. The reality is, questions and dissenting voices are a sign that people care about the decision being made. They want to understand the reasoning behind it, and they want to have a say in the process. And as a leader, it’s your job to listen to those voices, take their concerns into account, and plot an emotional path forward.

The alternative#

The best leaders I’ve worked with have always been open to dissenting voices. They’ve always been willing to listen to the other side of the argument, and to engage with it, even if they’re not willing to change their mind. The playbook is simple: be transparent, open, and accountable. This means:

Be transparent - Share the information, the data, and the evidence that informed your decision. Explain the criteria, the trade-offs, and the implications. Acknowledge the limitations, the uncertainties, and the challenges. Don’t hide, spin, or sugarcoat the facts. Be honest, clear, and consistent.
Be open - Invite the questions, the feedback, and the dialogue. Listen to the concerns, the objections, and the suggestions. Respond with respect, empathy, and curiosity. Don’t dismiss, deflect, or rebut the views. Be receptive, humble, and collaborative.
Be accountable - Take responsibility for your decision, your actions, and your results. Admit any mistakes, apologize, correct, and improve. Don’t blame, deny, or justify the faults. Don’t put the burden on others. Be honest, humble, and results-focused.

Conclusion#

While some see leadership as bold and courageous decision making in the face of a difficult situation, I would argue that covering one’s ears and humming in the face of after-the-fact questions shows a lack of leadership in the moment. It’s the equivalent of saying “I would have gotten away with it if it weren’t for you mangy kids…” (for those that grow up watching Scooby-Doo and other Saturday morning “who done it” cartoons).

The alternative to the “I don’t like what they’re saying so they shouldn’t be allowed to say it” approach is to embrace transparency, openness, and accountability. In practice: name the situation’s complexity, show the evidence behind your call, take your stakeholders’ questions head-on, and own your mistakes. Stay humble — listen, learn, and change course when the argument warrants it. And stay consistent: communicate often and honestly, and follow through on what you promised.

I’d take an engaged team that can have healthy, productive, and respectful disagreement any day over a team that’s checked out, indifferent, or apathetic. If they don’t care enough about this thing to speak up, it’s likely that there are other, bigger things that they’re not speaking up about either. ↩
A portmanteau of “care” and “mad”, meaning a software developer who is passionate, enthusiastic, and diligent about their work, and who cares deeply about the quality, functionality, and impact of their code and products. A caremad developer is not satisfied with mediocrity, but strives for excellence, innovation, and continuous improvement. For example, “She’s caremad about accessibility, she always makes sure every feature is compatible with screen readers and keyboard navigation.” ↩

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Cathedral vs Bazaar People Management

ben@balter.com — Fri, 08 Dec 2023 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

The Cathedral and the Bazaar is the book on open source. It contrasts closed source software development (the cathedral), where a centralized and hierarchical authority designs and builds a well-defined system, and open source development (the bazaar), where a decentralized community of contributors can browse, experiment, and collaborate within a modular and adaptable system. The book argues that the bazaar model is more effective, innovative, and resilient than the cathedral model, and in many ways, brought the ideals of the open source movement to the mainstream.

I’ve written before about bringing software development methodology to management, so what if we apply this cathedral vs. bazaar metaphor to people management styles?

Cathedral people management#

The cathedral manager is like the architect of the cathedral. They have a clear and detailed vision of what they want to achieve, and how to get there. They plan everything in advance and assign specific roles, tasks, processes, and standards to their team. They monitor and control their team’s work, and give them precise instructions, feedback, and guidance.

The cathedral style of people management is characterized by a high degree of control, direction, and standardization with problems and solutions being identified and defined in a top-down manner. Its advantage is that it can produce predictable and reliable results, especially in complex and stable environments. It can also create a much-needed sense of order, clarity, and security for members of the team, who find comfort in knowing what is expected of them and what they can expect in return.

The disadvantages of the cathedral style of people management are that it can stifle creativity, speed, and innovation among knowledge workers, especially in dynamic and uncertain environments that require a lot of experimentation and adaptation. It can also create a sense of rigidity, bureaucracy, and hierarchy for the team, who may feel constrained, micromanaged, and disempowered.

Bazaar people management#

The bazaar manager is like the organizer of the bazaar. Leaders in this style tend to have a broad vision, a flexible plan, and a flat network of roles and responsibilities for the team. The manager acts as the facilitator, the coach, and the enabler of the team’s work, defining goals and objectives and providing guidelines, feedback, and resources, while empowering the team to define their own tasks, processes, and standards, encouraging them to explore and innovate.

The bazaar style of people management is characterized by a high degree of autonomy and collaboration, with problems and solutions being identified and defined by the team. Its advantage is that it can produce innovative and resilient results, especially in dynamic and uncertain environments. It can also create a sense of freedom, empowerment, and ownership for team members, who can shape their own work, express their own voice, and pursue their own growth.

At the core of the bazaar style is the belief that team members are competent, self-motivated, and capable of aided self-direction. They encourage their team to explore their interests, share their ideas, and contribute their skills to further the team’s goals. This approach can also foster a culture of openness and trust among the members of the organization, who can learn from each other, support each other, and challenge each other.

Diagnose the situation, then pick your style#

Whether you’re a manager or an individual contributor (IC), know which style you default to—and which your manager defaults to. Your team might be a mix, or the right approach might shift depending on the scenario. That’s fine. The two styles typically differ in a few concrete ways:

By industry—The self-direction of the bazaar model wouldn’t be a good fit for the military, given the stakes. The cathedral model’s rigidity would suffocate a fast-paced startup that needs room to experiment.
By individual—A junior engineer needs the structure and clarity the cathedral model provides—“here’s the issue, here’s the approach, and here’s an example PR to reference.” A senior engineer might chafe at that much direction, preferring freedom to find problems nobody’s filed yet and propose solutions the team hadn’t considered. Likewise, some people are less comfortable living with ambiguity, while others prefer uncertainty and the autonomy that comes with it.
By role—Outside engineering, the cathedral model fits a line cook—the recipe is well-defined and consistency is everything. The bazaar model fits chefs who value creativity and experimentation as they seek to create new dishes.
By work environment—Distributed and async teams need more bazaar-style management because you can’t watch people work. Cathedral managers achieve visibility through direct oversight—standing over someone’s shoulder, literally or figuratively. In distributed teams, transparent workflows provide that same visibility without the micromanagement.

Find the right balance—and be willing to switch as the situation demands. Match the management to the moment. (share this quote)

Putting it into practice#

For managers: Distributed teams generally thrive with bazaar-style leadership because it emphasizes autonomy and trust—exactly what you need when you can’t see people working. But be ready to shift toward the cathedral when onboarding new team members, during crises requiring rapid coordination, or when establishing standards everyone must follow. The point isn’t ideological purity; it’s flexibility. If someone’s work starts slipping, lean into more cathedral-style management and the visibility advantages of working in the open until they’re back on track.

For ICs: Knowing your manager’s style helps you meet them where they are. If they lean cathedral, proactively share progress and ask clarifying questions before proceeding. If they lean bazaar, take initiative and document your decisions. Senior ICs often operate bazaar-style regardless of their manager—defining problems, proposing solutions, and bringing others along through influence rather than authority.

Cathedral and bazaar aren’t personality traits—they’re management operating systems you can swap depending on the moment. (share this quote) For distributed teams, the default should lean bazaar (autonomy plus transparency), but knowing when to shift toward cathedral matters just as much. As a manager, ask yourself: are you building a cathedral or a bazaar? As an IC, ask yourself: do you prefer working in a cathedral or a bazaar? And most importantly—are you and your manager on the same page? Get the balance right, and your team ships better work with less friction.

Out now

This post is adapted from my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

How to communicate like a GitHub engineer

ben@balter.com — Wed, 04 Oct 2023 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Transparent collaboration is the andon of knowledge work

ben@balter.com — Wed, 30 Aug 2023 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

The shift from waterfall to agile was predicated on the belief that what worked for the factory floor during the Industrial Revolution would not work for knowledge work in the Information Age, but assembly lines and modern software development have more in common than you might think:

Agile development can trace its roots back to the production floor of Toyota as far back as the 40s and 50s. At the core of the Toyota Production System (what eventually inspired the lean manufacturing movement) was the concept of an andon, a concept we continue to see driving benefit in modern software development today.

Anyone can stop the line for any reason#

In short, an andon is a system of lights and signals that allows workers to alert managers and colleagues to any problems or defects in the production process. With the pull of a cord or the press of a button at each station by any worker, the entire production system grinds to an instant halt.

The andon is designed to empower workers to stop the line, identify the root cause of the issue, and implement corrective actions, rather than letting it pass unnoticed or hoping someone else will fix it later. The andon is not only a tool for quality control, but also a culture of continuous improvement, where everyone is encouraged to speak up, share feedback, and collaborate on solutions. The andon fosters a sense of ownership, accountability, and learning among the workers, as well as transparency, trust, and alignment among the managers.

Transparency is software development’s andon#

Transparent collaboration in software development and other knowledge work is like the andon in a production system. It allows anyone to spot and call out critical issues early on, before they get worse, and to engage in constructive dialogue and problem-solving with their peers and stakeholders. Some of the benefits of transparent collaboration are:

Faster and better feedback loops - By making the work visible and accessible to everyone, transparent collaboration enables faster and more frequent feedback from users, customers, and colleagues. This feedback can help validate assumptions, identify gaps, and improve the quality and usability of the product or service. It can also help prevent misunderstandings, conflicts, and rework, as well as foster a culture of experimentation and learning.
Higher engagement and motivation - By giving everyone a voice and a stake in the work, transparent collaboration increases the engagement and motivation of the workers. It allows them to express their ideas, opinions, and concerns, and to contribute to the decision-making and problem-solving processes. It also allows them to see the value and impact of their work, and to receive recognition and appreciation from their peers and managers.
Greater trust and alignment - By creating a shared understanding and a common goal, transparent collaboration builds trust and alignment among the workers and the managers. It reduces the barriers and silos that can hinder communication, collaboration, and coordination. It also promotes a culture of honesty, openness, and accountability, where everyone is responsible for the quality and outcome of the work, and where everyone can learn from mistakes and successes.
Higher quality and customer satisfaction - By spotting and solving critical issues early on, you can prevent or reduce defects, errors, and rework, and improve the quality and usability of your software. By seeking and providing feedback throughout the process, you can ensure that your software meets the needs and expectations of your users and customers, and delivers value to them.
Faster and more efficient delivery - By making your work visible and accessible, you can reduce the overhead and waste of information silos, duplication, and handoffs, and streamline the software development process. By stopping the line and escalating issues when necessary, you can avoid or minimize delays, disruptions, and dependencies, and speed up the software delivery cycle.

Of course, transparent collaboration is not without its challenges and trade-offs. It requires a shift in mindset, behavior, and culture, as well as a set of tools, processes, and norms that support and enable it. It also requires a balance between openness and privacy, between collaboration and autonomy, and between feedback and focus.

Applying the andon principle to software development#

The benefits of transparent collaboration outweigh the costs, especially in a complex, uncertain, and dynamic environment, where the ability to adapt, innovate, and deliver value is essential. By adopting the andon principle in your own work, you can leverage the collective intelligence, creativity, and experience of your teams, and create better products and services for your users and customers. Here are some ways you can apply the andon principle to your software development team:

Make your work visible and accessible - Lean into transparency. Don’t view openness and early, broad engagement as a potential liability or risk that someone might “shoot down” your idea, but as an opportunity to get feedback and improve your work. Use tools and processes that allow you to share your work with your team and your stakeholders, and to solicit and incorporate their feedback. Don’t wait until the end of the project or the release cycle to get feedback. Instead, seek and provide feedback throughout the software development process, from ideation to deployment.
Stop the line and escalate issues when necessary - Don’t ignore or hide problems, or hope that someone else will fix them. Be proactive and responsible for the quality and outcome of your work. If you encounter a critical issue, such as a bug, a security issue, a performance degradation, or a user complaint, stop what you’re doing and alert your team and your stakeholders. Don’t resume your work until the issue is fixed, or a mitigation plan is in place. Learn from the issue, and implement preventive or corrective actions to avoid or reduce its recurrence.
Seek and provide feedback early and often - Don’t wait until the end of the project or the release cycle to get feedback from your users, customers, and colleagues. Solicit and incorporate feedback throughout the software development process, from ideation to deployment. Use techniques such as user research, prototyping, testing, and experimentation to validate your assumptions, identify gaps, and improve your software. Be open and receptive to feedback, and use it to learn and improve, not to blame or defend. Give constructive and timely feedback to others, and appreciate and acknowledge their contributions.
Collaborate and problem-solve with your team and your stakeholders - Don’t work in isolation, or assume that you have all the answers. Leverage the collective intelligence, creativity, and experience of your team and your stakeholders. Involve them in the decision-making and problem-solving processes, and respect their perspectives and inputs. Use methods such as brainstorming, design thinking, and retrospectives to generate and evaluate ideas, and to identify and address root causes. Communicate clearly and effectively, and align on the goals, expectations, and roles. Celebrate and share your successes, and learn from your failures.
Create a culture of continuous improvement - Don’t settle for the status quo, or assume that there’s nothing you can do to improve. Continuously reflect on your work, and look for ways to make it better. Use tools and processes such as retrospectives, postmortems, and root cause analysis to identify and address issues, and to implement preventive or corrective actions. Encourage and reward experimentation, learning, and innovation. Be open to change, and embrace new ideas and approaches. Don’t be afraid to fail, and learn from your mistakes. Share your learnings with others, and help them improve.

Conclusion#

Software development is not the same as manufacturing, but it shares some similarities. Both are complex, iterative, and collaborative processes that involve creating and delivering value to customers. Both also face challenges such as quality, efficiency, and innovation. And both can benefit from the andon principle.

The andon principle is not a silver bullet, but it’s a powerful tool for spotting and solving critical issues early on, and for fostering a culture of collaboration in your software development team. By adopting the andon principle, you can empower yourself and your team to stop the line when necessary, to collaborate and problem-solve with your peers and stakeholders, and to create better products and services for your users and customers. So, next time you encounter an issue in your software development process, don’t hesitate to pull the andon cord. Your team and your customers will thank you for it.

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Remote work requires communicating more, less frequently

ben@balter.com — Fri, 04 Aug 2023 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

Remote work is not simply a matter of replicating the office environment online. One of the key shifts that remote workers need to make is to communicate more, less often. Instead of relying on constant, synchronous, and often interrupt-driven interactions, remote workers embrace asynchronous, and often higher-fidelity, forms of communication, such as long-form writing or thoughtful videos.

I’ve written before about the benefits of working asynchronously, but less obviously, it also changes the way we think and work. Async work allows for more reflection, research, and synthesis. Those working async can and should take the time to think, learn, and synthesize before sharing their ideas, opinions, or solutions, distilling them down to the most critical. This improves the quality and clarity of the communication, and most importantly, the overall throughput of the communications channel.

Think of it like gzip compression, but for human-to-human communication. (share this quote) Yes, there’s slightly more processing overhead at the start, but it allows greater communications throughput using fewer “packets” (communicate more using less).¹ How can you communicate more, less often? Here are a few tips I often keep in mind:

Choose the right medium for the message (share this quote) - Remote workers should use the most appropriate and effective form of communication for the purpose, audience, and context. For example, use writing for documenting, explaining, or persuading; use video for demonstrating, teaching, or storytelling; use chat for coordinating, clarifying, or socializing.
Write clearly, concisely, and comprehensively - Remote workers should write with the reader in mind, using simple language, short sentences, and clear structure. They should also provide enough detail, context, and evidence to support their points, answer potential questions, and avoid ambiguity.
Record videos with empathy, enthusiasm, and engagement - Remote workers should record videos with a human touch, using eye contact, facial expressions, and voice modulation. They should also keep their videos short, focused, and interactive, using visuals, examples, and questions.
Communicate proactively, regularly, and asynchronously - Remote workers should communicate their goals, plans, and updates without waiting for prompts, requests, or deadlines. They should also communicate their availability, boundaries, and preferences without assuming or imposing. They should communicate asynchronously as much as possible, using synchronous communication only for urgent, complex, or sensitive matters.

Remote work requires communicating more, less often, because asynchronous communication involves less frequent, but richer communication, meaning there is less time talking about the work and more time doing it, allowing the system to optimize for throughput and flow.

Not to mention, thoughtful, written communication helps ideas to scale more effectively (there’s a reason the printing press spurred the Renaissance). It shifts communication from a one-to-one relationship to a one-to-many. Next time you’re about to “send a quick DM” or “schedule a quick chat,” consider what steps you could take to optimize for the long tail of information retrieval and discovery. Just like building a web app, “writes” are expensive, but “reads” should be “cheap,” so avoid introducing mental N+1s into the system whenever possible. ↩

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Practice inclusive scheduling

ben@balter.com — Fri, 19 May 2023 00:00:00 GMT

A new post from ben.balter.com · Read it on the web →

Time zones are one of the harder parts of software development, but it doesn’t have to be one of the harder (or exclusionary) parts of working as a distributed team. Here are a few practices that I try to adhere to help practice more inclusive scheduling when working remotely:

When discussing dates, consider writing numeric dates in ISO 8601 (YYYY-MM-DD) or other month/day unambiguous formats.
When referring to a time, always include the timezone.
Avoid location-specific language like “tomorrow”, “this afternoon”, or “in the spring”.
Be mindful of holidays, weekends, and working hours, especially across time zones.
Consider “speedy meetings” (end 5/10 minutes early or start 5/10 minutes late) to allow for time to be human between meetings, and be strict about ending at that earlier time.
On that note, meetings should start and end on time. If you finish early, consider using the remainder of the time for informal conversations and to connect as humans.

A small nod to inclusivity can go a long way to create a sense of belonging and reduce ambiguity, when working with global teams, schedule and communicate with a global (and remote) audience in mind.

Out now

This post inspired a chapter in my book, Open & Async.

The collaborative software development playbook for remote and distributed teams.

Buy it — $9.99 →

Ben Balter

It's pronounced JIF. The Open and Async audiobook is out.

The fight only exists out loud#

I recorded it wrong on purpose#

About the robot narrator#

Get the audiobook#

Footnotes#

Accessible by default: writing a book like software

Markdown won’t let you fake structure#

Markdown can’t check the parts you didn’t write#

Contrast doesn’t exist until the render#

What the checks can’t see#

Accessible is a synonym for inclusive#

The reader sets the terms#

Exclusion dressed as preference#

Readers you’ll never meet#

A screen reader and a language model want the same thing#

Structure is the interface#

The file has to open first#

Steal this#

Footnotes#

How I over-engineered my book

Content#

Testing#

Real-time#

On each push#

Audits#

Duplication detection#

Content audits#

Probabilistic (LLM) audits#

Deterministic audits#

Design#

The invisible leak#

Tests#

Accessibility (axe-core)#

Visual & layout regression (Playwright)#

Building#

A reproducible toolchain#

Pre-processing (before Pandoc sees the text)#

CSS pipeline#

Lua filters (the interesting part)#

The dark box#

Rendering & post-processing per format#

Testing the build#

Publishing#

Looking forward#

Conclusion#

By the numbers#

Footnotes#

Open and async on the Overcommitted podcast

Open and Async: the remote-work playbook is out

What separates teams that thrive#

Who it’s for#

What’s inside#

Work loudly

Work in the open, not in a summary#

Like a bear bell#

Loud, not bragging#

The payoff compounds#

Managing without surveilling#

The trail test#

Reorgs happen

Why reorgs happen#

Why they feel so disruptive#

Treat reorgs as a constant, not an exception#

How to navigate a reorg#

How to make the most of one#

The long view#

Footnotes#

AI-first program management

From async to AI-augmented#

AI across the PM toolkit#

Communication, coordination, and facilitation#

Capture and track work#

Risk identification and mitigation#

Reporting up and across#

Relationship management#

Consensus and conflict resolution#

What doesn’t change#

What changes for PMs#