Ben Balter

Reorgs happen

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

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#

If reorgs are so routine, why do they hurt? Because the costs are real and they’re personal: you lose context, you lose working relationships you spent months building, and you have to renegotiate trust with a new manager who has no idea what you shipped last quarter. Add uncertainty about priorities—is my project still funded? is my role still valued?—and it’s no wonder a Monday-morning announcement can derail a whole week.

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.

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 speaks for itself, 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.

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. ↩
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. ↩

AI-first program management: amplifying judgment, not replacing it

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

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.

These ideas aren’t disconnected. They’re an evolution.

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. It accelerates it.

AI across the PM toolkit#

Here’s how each core PM responsibility shifts when AI enters the picture — and where it doesn’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. The opposite is true.

The responsibilities haven’t changed. Communication, risk management, relationship building, consensus-driving — these are still the job. What’s shifted is the ratio of information processing to judgment in a PM’s day. AI handles more of the former so you can focus more on the latter.

The things AI can’t do are precisely the things that make great PMs great: reading a room, building trust over months, knowing when to push and when to back off, navigating organizational politics, and making the hard call when the data is ambiguous. These are human skills, and they become more valuable as AI handles the routine work, not less. When everyone has access to the same AI tools, the differentiator is the human wielding them.

What changes for PMs#

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

Prompt craft matters. The quality of what AI produces depends entirely on the quality of what you ask for. It’s garbage in, garbage out — a principle as old as computing, now pointed at prompts instead of punch cards. PMs who can write clear, specific prompts — essentially, good requirements — will get dramatically better results than those who can’t. It turns out that years of writing crisp issue descriptions and well-defined acceptance criteria is excellent training for working with LLMs. Good requirements have always been a PM superpower. Now they’re a superpower twice over.

Knowing when not to use AI is as important as knowing when to use it. A sensitive personnel conversation, a politically charged escalation, a message to a stakeholder who’s having a rough week — these require a human touch that AI can’t fake. Developing judgment about when AI helps versus when it gets in the way is a skill in itself, and it’s one that’s hard to teach in the abstract.

Verification becomes a core competency. AI will confidently summarize a thread and miss the most important nuance. It’ll draft a status report that’s 90% accurate and 10% dangerously misleading. PMs need to be skilled editors and fact-checkers, not just consumers of AI output. The role shifts from author to editor-in-chief — you set direction, review drafts, and ensure quality before anything ships.

AI fluency is table stakes. Just as PMs were expected to be comfortable with project management tools, version control, and whatever collaboration platform their teams use, they’ll be expected to work fluently with AI assistants. Not as a novelty, but as a core part of the daily workflow — the way we already think about Slack or email or GitHub Issues.

The PM as orchestra conductor#

The mental model I keep coming back to is the program manager as orchestra conductor. A conductor doesn’t play every instrument — they don’t play any instrument during the performance. But they’re essential: they set the tempo, bring in the right sections at the right time, interpret the score, and turn individual performances into a coherent whole.

AI agents are new instruments in the orchestra. They play fast, they play consistently, and they can handle parts that used to require a human musician. But someone still needs to read the score, understand the audience, and make the hundred small decisions that turn a technically correct performance into something that actually moves people. That’s the PM’s job — and it always will be.

The shift from synchronous to async made program management more intentional. Managing like an engineer made it more transparent. AI makes the same hours count for more. Each evolution builds on the last, and each one makes the human judgment at the center of the work more important, not less.

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. ↩

How to one-on-one

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

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 categories keep coming up:

Career growth and development. Where do you want to be in a year? What skills do you want to develop? These conversations require back-and-forth exploration, picking up on what’s left unsaid, and nuanced guidance that doesn’t fit in an issue comment.
Coaching and problem-solving. When you’re stuck on an interpersonal challenge, unsure how to approach a sensitive topic, or wrestling with a decision that has no clear right answer, talking it through with someone who has context beats wrestling with it alone.
Feedback and calibration. Feedback—giving and receiving—lands better in real-time. Tone and body language provide context that text can’t, and you can clarify misunderstandings immediately. Written feedback can feel blunt or land wrong; spoken feedback invites dialogue.
Human connection. Remote work can be isolating. 1:1s let you check in as humans, not just workers. How are you actually doing? Building genuine relationships requires face-to-face time, even if that face is on a screen.
Clearing the air. If there’s tension, frustration, or something unsaid, 1:1s are the place to address it directly. These conversations are almost always better synchronously than through a wall of text.

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. 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? 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.

The brag doc

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

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.

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.” We’re conditioned to believe good work speaks for itself—that tracking your wins is unseemly.

It’s not.

The alternative is being invisible. And invisible people don’t get promoted—they get overlooked, then they leave. Ship early, show your work, and keep the receipts.

If sharing your wins feels gross, reframe it: you’re not bragging, you’re making your manager’s job easier. When promotion conversations come around, you’ll have months of evidence instead of a frantic scramble to remember last quarter.

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. Start the doc today—future you will be grateful.

No agenda, no meeting

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

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.

Why this matters#

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.

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.

Agentic workflows and the future of software development

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

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. ↩

I've worked remotely at GitHub for thirteen years: here's what actually works.

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

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. 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. ↩

How to run LanguageTool on macOS

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

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. 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. ↩

The "I don't like what they're saying, so they shouldn't be allowed to say it" approach to crisis management

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

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 ever 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 its 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 is comprised of the underlying assumptions that its members use to make decision. 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 go 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. This means acknowledging the complexity and uncertainty of the situation, explaining the rationale and evidence behind your decision, inviting and addressing the questions and concerns of your stakeholders, and admitting and correcting any errors or shortcomings. This also means being humble and curious, listening and learning from others, and being willing to change your mind or course of action when warranted. This also means being clear and consistent, communicating often and honestly, and following through on your commitments and promises.

I’d take an engaged team that can have healthy, productive, and respectful disagreement any day over a team that’s checkout 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.” ↩

Cathedral vs Bazaar People Management

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

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. Here’s how the two styles typically differ:

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.

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. 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.

How to communicate like a GitHub engineer

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

How GitHub turned its guiding communication principles into prescriptive practices to manage internal signal-to-noise ratio.

Transparent collaboration is the andon of knowledge work

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

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. It may seem counterintuitive to make it easier for anyone to shut down production, but the idea is that if you stop the line as soon as a problem is detected, it can be fixed before it gets worse. It’s been so successful in driving continuous improvement that Toyota (and most other manufacturers) continue to use the concept to this day.

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.

Remote work requires communicating more, less frequently

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

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. 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 - 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. ↩

Practice inclusive scheduling

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

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 inclusively to 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.

Pull requests are a form of documentation

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

We often think of pull requests purely as a code review mechanism, but they are also an organic and natural form of documentation. I can’t count the number of times I’ve spelunked historic GitHub PRs to understand the context around a feature or product decision.

Pull requests capture not just what change was made, but who made it, why, and what alternatives were considered. They create a cross-linked web of context for others, and capture the discussion around the change, which is often an equally valuable technical artifact.

When I write a PR, I write it not just with the immediate reviewers in mind, but how it will read for outsiders down the line who might land on in from search results or a cross reference. Beyond documentation, PRs are a great place for your colleagues to ask the type of “dumb questions” that gives you the confidence to ship.

To that end, here are a few practices I follow when authoring pull requests to ensure I’m capturing sufficient context for myself and future contributors:

Descriptive title - Avoid the default Update FILE.md and instead use the title to capture the essence of the change in a way that is clear when scanning a list of PRs
Brief description of the change - Right up front, add a quick TL;DR describing the “what” of the change for others landing on the PR from search or a cross link so that they can quickly understand the change
Ensure the body describes the “why” - Equally essential as the “what” is the “why”. Why is this change being made? What problem does it solve? What alternatives were considered? What are the trade-offs? What are the risks? Be sure to include relevant links.
Enough context - So that others outside your team (or yourself years from now) can understand the change. Think of it as a time capsule or a message in a bottle to your future self and future contributors.
@mention responsible team - if not automatically requested via CODEOWNERS. Not only does this bring visibility to the PR, it also makes ownership clear by explicitly calling out the responsible team. Be sure to include why you’re @mentioning the team (what action is requested, if any) so that it’s surfaced in the notification.
CC or fixes related issues - to create a trail of breadcrumbs to improve discoverability and allow others to opt-in to additional context. As an added bonus, it will auto close the tracking issue for you.
Task lists - To reflect the current state of the PR - for example TODO: add tests and to capture process
Screenshots or animated GIFs - to illustrate UI changes without requiring other to spin up a dev environment
In-line documentation - Linking back to the PR from the code itself for especially complex or nuanced changes
Review your own PR - Comment in line to highlight specific changes for reviewers that you’re less confident on.
Discrete changes - Avoid bundling unrelated changes into a single PR which can hinder future discovery and understanding. Bonus use atomic, descriptive commits within the PR.

Yes, organic documentation takes slightly more time, but it’s less overhead than keeping static documentation up to date, and I promise you, it’s well worth it - your future self (and future coworkers) will thank you.

For even more tips, check out how to write the perfect pull request on the GitHub Blog.

Meetings are a point of escalation, not a starting point

ben@balter.com — Thu, 20 Apr 2023 00:00:00 GMT

Asynchronous communication (Issues, PRs, Google Docs, and sometimes Slack) should be the default, reserving more synchronous media (like video calls and in-person meetings) for the types of conversations that uniquely benefit from their higher fidelity (brainstorming, whiteboarding, interpersonal conflict, social connection, etc.). Put another way, the phrase “async first” should be taken literally.

Default to transferring context asynchronously#

When starting up a new initiative or collaborating with a colleague for the first time, it’s often tempting to “throw some time on their calendar” to “kick things off”. Such kickoff meetings often consist primarily of an information download, sharing context from one coworker to another with a specific call to action or request for feedback. But information transfer isn’t always the best use of synchronous time, especially when you consider the overhead of scheduling (especially across time zones), scaling (O(n) vs O(1)), and memorializing outcomes (as durable artifacts available to others). Not to mention, different people have different learning styles—not everyone absorbs information best via voice and in real time.

Instead, next time, consider transferring that context asynchronously (as a GitHub issue or Google Doc, for example), and then scheduling a meeting only if the conversation requires it—you’d be surprised how often it does not. A few minutes of reading or a few comments on an issue or Google Doc can often replace waiting days for mutual availability and a dedicated 30-minute block of time. In this sense, you can think of meetings as a point of escalation based on complexity, not as the default starting point for a workstream, initiative, or conversation.

Meetings are not where work happens#

You may be skeptical. I was curious, so I wrote a quick script to pull stats from my own calendar. My first year at GitHub (2013), I had a grand total of 16 internal meetings. Yes, we were smaller back then, but we were also dogmatic about being async first, almost to a fault. As we grew, my second year I had 43 meetings, and things gradually increased from there. This year, I’m on track to have over 600 meetings. There’s got to be a better way!

meetings-over-time

Working asynchronously by default fosters a more inclusive culture, facilitates discoverability and permanence, creates space for learning, allows for greater work-life balance, and produces better outcomes, faster. Async is also the key to making remote work, work.

Hold colleagues accountable for being truly async first#

If you receive a meeting invite (or if a colleague requests permission to send you a meeting invite) without context, an agenda, or a read-ahead doc, consider politely declining, or at least asking for one—it’s well within your rights (you can even link to this discussion post as a “get out of ~~jail~~ meeting free” card). After all, if the person requesting the meeting hasn’t taken the time to distill their thoughts into writing, why should they be able to decide how you spend your own time?

Intro to GitHub for non-technical roles

ben@balter.com — Thu, 02 Mar 2023 00:00:00 GMT

What is GitHub?#

If you’re not a software developer, you can think of GitHub like Dropbox, Google Drive, or SharePoint, but for software development. It’s primarily used by software developers to collaborate on software and track their progress, but can be used by anyone involved in the software development process.

Repositories#

Repositories are the most basic unit of GitHub. Each repository represents a real-world project, initiative, or team. Repositories contain issues, discussions, and pull requests (more on that in a moment), as well as “code”, which for non-technical roles, is often text files in the form of Markdown (more on that too).

Markdown#

Markdown is how text is formatted on GitHub. If you wanted to format text in a text box that didn’t support formatting, you might use *s to represent bullets, or wrap a word in _ to emphasize it. That’s Markdown. Markdown is plain text, with optional lightweight formatting that GitHub can render. It sounds like “coding”, but you’ll get the hang of it in no time. To get started, check out the official GitHub docs.

Pro-tip: To convert a Word or Google Doc to Markdown, you can use my very own Word to Markdown converter.

Issues#

Issues are how work is tracked on GitHub. You can think of them as “To Do” items (or “tickets” in some contexts). Issues describe the problems you or your team want to solve, with the list of potential problems being referred to as the team’s “issue backlog”. You can comment on issues, like you would a blog post, assign them to people, and close them when they have been completed. Issues can also be labeled for ease of discoverability and for tracking additional metadata. For especially complex problems, the body of the issue can even include a task list with checkboxes, to track progress of individual sub-tasks.

Discussions#

Discussions are like issues, but don’t have a specific outcome or sense of state (open or closed). You can use discussions to ask questions, collaborate on ideas, and share announcements. You can think of discussions like blog posts, an online forum, or a chat room for your repository.

Pull requests#

Pull requests are how you propose changes to a repository. If issues describe the problems, pull requests describe the proposed solutions. Others can also review your proposed changes and comment on, make suggested changes to, or “approve” your pull request. Pull requests modify files within the repository. Once approved, your pull request is “merged” into the repository and your proposed changes are “live”.

Markdown files#

Repositories contain files. These files can be anything, but are often text files in the form of Markdown. You can edit these files directly on GitHub, or you can clone the repository to your computer and edit them there (more on that below). You can also upload files directly to GitHub by dragging-and-dropping them. Generally filenames are lower case and use hyphens instead of spaces. Files as Markdown is generally how long-lived information is shared and stored (documentation, policy, procedures, etc.).

Tracking changes#

At the core of GitHub is a version control system called Git. Git tracks changes to files over time. You can think of it like tracked changes in Google Docs or Microsoft Word (or if you’re into sci-fi, a time machine for your files). You can see who made changes, when they were made, and what the changes were. You can also “roll back” changes to a previous version of a file.

Commits#

Git tracks changes as “commits”. A commit is a snapshot of the file (or files) at a point in time. Each commit should have a brief, descriptive message describing the changes from the previous version, to help you and your colleagues understand what’s going on.

Branches#

Branches are like parallel universes or alternate timelines for your files. You can make changes to a branch without affecting files on the “main” branch. Branches contain one or more commits, and when you’re ready, you can merge your changes (commits) into the main branch to update the files there. You can think of branches as saving a copy of a file so that you can work on changes without affecting others’ work, but in a way that makes it easier to merge any changes you make back in with the original when you’re ready.

GitHub flow#

GitHub flow describes the process of making changes to a repository. The basic steps are:

Open an issue describing the problem you want to solve
Once there is agreement that the problem should be solved, decide on the best solution
Create a branch to work on the solution
Make changes to files on the branch
Commit those changes
Open a pull request “requesting” that those changes be merged back into the “main” branch
Your colleagues review your pull request and either approve it or suggest changes
Once approved, your pull request is “merged” and your changes are now “live” on the main branch

Notifications#

GitHub sends notifications to you when someone mentions you in a comment, assigns you to an issue, or requests your review on a pull request. You can also (and often should) “subscribe” to repositories to be notified about some or all activity. Likewise, you can unsubscribe from individual issues if you’re not interested. By default you’ll receive notifications via email, but you can also configure GitHub to use “web notifications”, or even set up notifications in your Slack or Teams channel.

@mentions#

One of the most powerful GitHub features is @mentions. You can tag anyone into an issue or pull request by typing @ followed by their GitHub login. They’ll receive a notification and can respond. You can also use @mentions to tag teams, like @github/eng or @github/eng-ops. When @mentioning users or teams, it’s best to provide context in the comment so they know why they are receiving the notification.

Cross references#

Another powerful GitHub feature is issue and pull request cross references. You can reference another issue or pull request in a comment by including its number (for example, This is related to #123). When cross referenced, links are created between the two issues or pull requests, making it easier for others to discover and understand the context of the conversation.

Desktop vs. web#

Almost everything you’d want to do on GitHub you can do entirely through the web interface. You can view, create, edit, or delete files, browse and comment on issues, and merge pull requests. If you’d prefer to work on your desktop using your favorite desktop software, you can install GitHub Desktop. GitHub Desktop provides a visual interface for “pulling” (downloading) repositories onto your computer and interacting with GitHub.

Advanced-ish topics#

Pushing and pulling#

If you’re using the web interface, you don’t have to worry about pushing or pulling. If you’re using the desktop client, you can think of pulling as downloading the files from GitHub and pushing as uploading the files back to GitHub. (Before pulling, you need to clone, or create a copy of, the files.)

Emoji and animated GIFs 🎉#

In addition to Markdown you’ll often see emoji and animated GIFs used heavily on issues and pull requests. You can think of emoji and animated GIFs as the facial expressions and body language of GitHub. They make it easier to convey emotion in written text. I like to describe the communication style on GitHub as “professional but informal”, meaning don’t be afraid to use emoji and animated GIFs to make your comments more expressive (while remaining appropriate, of course).

Project boards#

If individual tasks are tracked as issues, project boards are how you track the progress of a project as a whole. Project boards are a visual representation of what issues are on deck, what issues are in progress, and what issues have been completed (todo, doing, done).

Finding information#

With so much information available on GitHub, it’s often intimidating to find what you’re looking for. Here are some tips for using GitHub’s powerful search to find anything on GitHub:

Use keyword search, just like you would any search engine. For example, searching for widgets will find all repositories, issues, pull requests, and discussions that contain the word “widgets”.
Scope your search to an organization or repository by using the org: or repo: qualifiers. For example, org:github will find all issues in all repositories in the github organization, or repo:github/docs will find all issues in the github/docs repository.
You can further refine your search to only show threads that you’re involved in by using the involves:@me modifier. For example, widgets involves:@me will find all issues, pull requests, and discussions that contain the word “widgets” and that you are involved in.
Different types of information (issues, pull requests, discussions, Markdown) are displayed as separate results. Be sure to check the side bar to see all the different types of information that match your search.
You can limit a “code” search to only Markdown files, by clicking “Markdown” in the sidebar to filter results, or adding language:Markdown to your search query.

Official docs.

Checks#

You may see one or more status checks on your pull request. Checks are automated tests that run against your proposed changes to enforce certain rules (such as formatting, spelling, or style). If a check fails, you’ll need to fix the problem before your pull request can be merged. You can click “details” next to a failed check to learn more.

When to use an issue vs. a pull request vs. a discussion vs. a Markdown file vs. a project board#

Project work generally flows in this order:

Discussions - Open-ended conversation without a specific outcome or concept of “done”. This is often the ideation or brainstorming stage.
Issues - How problems are tracked, discussed, and prioritized.
Pull requests - How solutions/changes are proposed and reviewed. Generally pull requests should tie back to the issue/problem they are solving.
Markdown files - How long-lived information is shared and stored (documentation, policy, procedures, etc.). Markdown files are changed via pull request.

As a project proceeds in one or more repositories, high-level project progress is tracked on one or more project boards (which visually organizes the state of multiple issues).

Putting it all together, editing a file on the web#

Open the repository you want to edit
Navigate to the file you want to edit
Click the pencil icon to edit the file
Make your changes
Click “Commit changes” to save your changes
Describe your changes in the commit message
Name your branch
Click “Propose changes” to open a pull request
Describe your changes in the pull request, ideally referencing the issue you’re solving (for example, Closes #123)
Your colleagues review your pull request and either approve it or suggest changes
Once approved and checks pass, your pull request is “merged” and your changes are now “live” on the main branch
Celebrate your first contribution to GitHub!

Glossary#

If you come across a term or concept not covered here, be sure to check out the official GitHub glossary.

Happy GitHubbing! 🎉

How to write a great extended leave document

ben@balter.com — Fri, 13 Jan 2023 00:00:00 GMT

I recently came back from an extended leave to find several of my colleagues asking to copy my “leave doc” for their own planned leaves. Having transitioned roles within GitHub now a number of times over the years, I’m no stranger to temporarily or permanently handing off work, and have evolved a preferred format I use to ensure business continuity during the transition. In service of “everything should have a URL”, I’m sharing my leave template here in case it’s helpful for planning your own leave.

Sections to include#

⏳ TL;DR#

“Too long, didn’t read”. This is for the folks who have a question or request, but don’t have time to read the whole document. Put it up front and make it visually distinct. The TL;DR can be as simple as:

If your question or request isn’t answered below, open an issue in X or post in Y and someone will point you in the right direction. Wondering the status of an in-flight project? Check out Z.

📅 Dates#

When is your last day in the office? When do you anticipate being back? If the exact date of your leave is unknown, you can provide an estimated range, or describe the leave in relative terms (for example, event + 2 weeks). Keep this section up to date as your plans change. Here’s an example of what that might look like:

	Start	End	Dates
First Leave	Event	Event + 2 weeks	1/1/2020 − 1/15/2020
Second Leave	Event + 4 weeks	Event + 6 weeks	2/1/2020 − 2/15/2020

☎️ Contact preferences#

How do you want to be contacted while on leave, if at all? What do you want to be contacted about? What’s considered urgent? Set expectations as to how often you will be checking email, Slack, your phone, and so on if you are going to check them at all, so that colleagues know how to get in touch with you, and when to expect a response.

✍️ Points of contact#

Enumerate all your ongoing responsibilities, along with a point of contact that will be responsible while you are on leave. Be sure to include “points of escalation” for anything not accounted for within your doc, and be sure to check with each named individual to ensure they are comfortable with the responsibility and have the bandwidth to take it on. Consider a dedicated “responsibilities to handoff” section for any key milestones, deadlines, or events expected to occur while you are out. Example:

What	Who
Widget production	Walter
People management	Paula

📹 Regular meetings#

List any recurring meetings you normally run or attend, their frequency, and who if anyone will be taking your place at those meetings. Be explicit with any host or presenter responsibilities, and include links to standing agendas or other supporting documents.

Meeting	Frequency	Responsibilities	Who
Staff meeting	Mondays @ 10 AM	Set agenda, run	Susie
1 with directs	Weekly	Take notes, follow up	Danny

👥 Rolodex#

For everything you touch regularly, list your primary point of contact. This will allow others to unblock themselves if they have a question or request of another department or team. Example:

What	Who
HR	Henry
IT	Iris
Legal	Larry
Finance	Fran

👉 Stuff you touched recently or hope can be picked up while you’re out#

List any projects, initiatives, or other work you’ve been involved in recently, and any that you hope to be able to hand off to others while you are out. I linked out to our team project board, which captured the in-flight work, and created a “@benbalter’s GitHub Fan Fiction” document, with the backlog of ships that I had hoped would be GitHub cinematic universe cannon before going on leave. My fan fiction looked something like this, framed in terms of problems and solutions:

Problem: I’m going on leave and want to ensure that the work I’ve been involved with recently is not lost or forgotten while I’m out.

Ben’s solution: Write a great leave doc.

Ideal DRI: @benbalter

📁 Important links#

This is your long-tail appendix of anything you think your colleague might need while you’re out. This could include links to team documentation, commonly referenced spreadsheets or reports, planning materials, or anything else you think might be useful.

You could have the best leave or transition document in the world, but if nobody knows about it, it’s not much use. Socialize the document with key stakeholders well before your leave to ensure accuracy and completeness¹, and make your document readily discoverable while you are out by linking to it from your chat status,² the out of office on your calendar, and any other “APIs” you have for communicating with colleagues.

Putting it all together#

If you’re preparing to go on leave (or transition to a new role), feel free to use the template below as a starting point.³ Of course, if you have any suggestions or proposed improvements, pull requests are always welcome.

# @your leave document

## ⏳ TL;DR:

## 📅 Dates

## ☎️ Contact preferences

## ✍️ Points of contact

## 📹 Regular meetings

## 👥 Rolodex

## 👉 Stuff you touched recently or hope can be picked up while you're out

## 📁 Important links

I often ask, “Are there any questions not answered here that you can imagine might arise while I am out?” ↩
Using an internal or external link shortener (for example, bit.ly/benbalter-leave) to create a more memorable URL for your colleagues to regularly reference your doc. ↩
If you’re looking for even more extended leave resources, @isethi has a great talk on navigating parental leave as a senior engineering leader. If you’re preparing to go on parental leave, be sure to check out her parental leave checklist template as well. ↩

Manage like an engineer

ben@balter.com — Tue, 10 Jan 2023 00:00:00 GMT

Many engineering and product leaders begin their careers as engineers. On a typical engineering team, work is captured in issues, organized in project backlogs, and reviewed in pull requests. For most teams, this is the best way to plan and track software development work.¹ But as engineers advance in their careers and begin down the management path, they too often adopt an entirely different set of tools, workflows, and philosophies for managing their own work. Such management workflows are more cumbersome, more time-consuming, and more opaque than their engineering counterparts. If we believe issues, pull requests, and project boards are the best way to develop software, should they not also be the best way to manage software development?²

Rather than tracking bugs or feature requests, in my day-to-day as a Chief of Staff, I use GitHub to track all the “meta work” that supports software development and software development teams. Need to prepare a deck for a business review? Open an issue. Want to refresh our career ladders? Open an issue. Planning an offsite? You guessed it, open an issue.

Why you should manage like an engineer#

Using engineering tools like GitHub to track management tasks is much more than an alternative to your personal todo list or an endless stack of Google Docs or group DMs shared with peers. Working like an engineer forces you to work more transparently than you would traditionally as a manager. I’ve written at length before about the value of leaders “showing their work”. When you work in systems that naturally capture and expose process, there are a lot of organic benefits that you and your team get for “free”:

Captures institutional knowledge - When you’re purposeful about where and how you share context, you alleviate the need for “you had to be there” and “go ask Susan”-type inquiries.

Empowers others to learn through observation - What’s routine to you is likely novel to someone in another role or at another level of seniority.

Socializes organizational culture and values - An organization’s culture and values are composed in large part of the underlying assumptions that its members fall back on as they resolve ambiguity in pursuit of the organization’s mission.

Fuels engagement - Transparency offers a sense of agency, situational awareness, and overall engagement that fosters a culture of thoughtful dialog and encourages organization-wide collaborative improvement over time.

Keeps the bar high - Showing one’s work establishes expectations around justification, thoroughness, and accountability that sets and maintains a high standard for decision making within an organization.

What it means to manage like an engineer#

This level of open-source-like managerial transparency is far from automatic or the default for most management workstreams today. The software tools we use as managers may help influence some outcomes,³ but ultimately, leaders must be deliberate in how they work for their team to reap the benefits of transparent and collaborative decision making.

Here are a few of the engineer-inspired “how we work” principles which I strive to embody through my own management:

Make work visible - Proactively share to the widest extent practical given the subject.⁴ Like any production system, observability is key.
Write things down - Especially the why and how. Ensure that everything has a URL. Be generous with links.
Over communicate - Use a durable, searchable, and discoverable medium. Let others opt-in to context and subscribe to updates.
Bias for shipping - Ship early, ship often. Whether decisions, process, or “manager code”, ship an MVP and iterate. Minimize batch size.
Streamline and automate - Never force a human to do what a robot can. Prefer non-blocking over blocking operations. Codify policy as code.
Embrace collaboration - How we work is as important as what we work on. Software development is a team sport.⁵
Asynchronous first - Reserve higher-fidelity mediums for conversations that require them.
Practicality beats purity - These are guidelines, not rules. Process should drive outcomes.

How to manage like an engineer#

Managing like an engineer means a manager’s go-to tools for planning, tracking, and communicating managerial work are issues, project boards, Markdown files, and pull requests:⁶

Issues - Issues are the atomic unit of work across teams and are the primary means by which work is planned, tracked, coordinated, and communicated, and where updates are shared.⁷
Project boards - Project boards are the primary means by which work (in the form of issues) is organized, managed, prioritized, and made visible.
Markdown files - Markdown files are the primary means by which long-lived information is memorialized. Markdown files are created and modified via pull requests.
Pull requests - Pull requests are the primary means by which proposals are reviewed and decisions are made.

Planning and tracking#

Issues and project boards create a networked hierarchy of tracking issues that bring visibility to work. This is true both of department-wide goals and initiatives, as well as all the management “meta work” that supports them.

I’ve written at length before about how we use issues and projects at GitHub for planning and tracking. We use issues and a project board to track our department-wide OKRs (quarterly goals). Teams may choose to organize issues with labels, milestones, assignees, and project boards to aid in planning and tracking. Issues can capture work at various levels of abstraction, with different “types” of issues encompassing different units of work (initiatives, epics, etc.).

All of the department’s management tasks are also tracked in issues, which are made visible to everyone in the company as a management backlog via a GitHub Project. Interested stakeholders wishing to learn more about a given initiative or administrative epic can click into the linked issue to learn more or subscribe to automatically receive ongoing updates.

Management decision records#

Successful distributed teams place an emphasis on written and asynchronous communication. Writing things down serves as a message in a bottle to your future selves, recording what decisions were made, by whom, and why. If issues and project boards track and organize work, “management decision records”,⁸ socialized and discussed via pull requests, are how decisions are made and communicated.

One common way engineering teams capture important decisions is through an architecture decision record (ADR). ADRs capture not just the decision, but also its context and consequences, and do so in a way that allows stakeholders to deeply participate in the process. In short, the person responsible for a decision writes out their proposal in long-form prose, and submits it for discussion and refinement by stakeholders before it is ultimately merged to memorialize the decision.

While ADRs are intended for engineering decisions, the format and rigor of documentation and process can be adapted to any type of impactful or long-lived decision, especially management decisions with broad impact. That’s not to say that management decision records democratize or crowdsource management. Rather, it formalizes and makes transparent the socializing process that already happens when making such management decisions.

Automate all the things#

Better still, since GitHub is an extensible platform, automation of day-to-day issue management can be “cheap” to implement via shared GitHub Actions. If a given OKR hasn’t received an update in a while, we use Actions to nudge the responsible individual. When status updates come in as issue comments on a regular cadence, Actions updates the project board so that the health of all our OKRs can be seen in a single view. We even use Actions to automate issue creation at the kickoff of the planning cycle, or to have regular meeting and 1

agendas created each week.⁹

Conclusion#

A decade ago, I argued that working like an open source project would allow us to “Deprecate Management”. As I wrote then:

There are so many aspects to the work day that we do just because it’s the way things have been done since the dawn of the industrial revolution, and it puzzles me why nobody’s stopped to think critically about how these processes could be reimagined in an age of technology.

Today, I don’t believe that a complete “deprecation” of management is possible, at least not at scale, but by working in the open, managers can shed a lot of management meta-work, moving managers from lower-level to higher-level, more impactful work.

Managing like an engineer means using the same tools and workflows that engineers use to plan, track, and communicate their own work. It means making work visible, writing things down, and embracing collaboration. After all, if that’s the best way to build software, should it not also be the best way to manage software development?

Yes, there are different flavors and tools (agile, scrum, Jira tickets, etc.), but at a high level, most teams have some sort of ongoing list of outstanding todos, along with a standard mechanism to review proposed changes. ↩
Long before the term “inner-source” became popular, GitHub had co-opted the workflows and communication patterns of the open source community for its own internal development. While much has been written over the years about “how GitHub uses GitHub to build GitHub”, the concept of using GitHub to manage GitHub fell out of popularity as GitHub grew (and outgrew its own tools). Now that GitHub has native planning-and-tracking capabilities, it’s the perfect tool for managers. ↩
For example, transparent and inclusive decision making comes more naturally in a tool built for collaboration like GitHub than it does in a tool built for conveying information like Slack or email. That’s not to say it can’t be done, but the tool’s vision of how work should occur and yours may differ, making things more difficult on both you and your team. When in doubt, start from first principles and ask yourself, “what is the best tool for the job?” ↩
HR and other personnel matters must often be restricted in their visibility due to their sensitivity, but the vast majority of management work can be shared with increasing circles of trust (peers, other managers, the team, the org, the company, etc.). I’ve even seen one team use Mermaid diagrams in Markdown files to visualize their org chart. Re-org by PR? 🤔 ↩
Encourage collaboration among team members, both in terms of setting team-wide goals and executing on individual initiatives. This helps everyone “connect the dots” and understand how their work fits into the bigger picture (and to shape it along the way). ↩
I write about my experience using GitHub, but there’s no reason these philosophies couldn’t be implemented using another engineering tool. The key is to use a tool that is built for collaboration and transparency and that is extensible via automation. ↩
Track tasks and their progress in issues, cc relevant teams, and cross reference relevant issues to naturally capture and expose process. Issues bring the most value to teams when work happens on and around the issue, rather than holding important discussions in chat or over video with the issue being used merely as a TODO with tracking open and closed state or a broadcast medium for occasional formal updates to stakeholders (for which Discussions are better suited). ↩
Depending on the context, these may also be referred to as “business decision records” (BDRs). ↩
Taking the metaphor further, there’s no reason why a manager’s workflow couldn’t have its own “CI”, in the sense that automated checks could keep a high bar for, for example, decision making by ensuring necessary stakeholders were consulted, that ample opportunity was offered to provide feedback, and so on. We use this lightly in some places to encourage inclusive language or readability of documentation. ↩

Helpful 404s for Jekyll (and GitHub Pages)

ben@balter.com — Thu, 30 Jun 2022 00:00:00 GMT

While the internet has long had a soft spot for clever 404 pages, it’s rare to see one that’s actually helpful, especially for static sites like Jekyll or GitHub Pages that make dynamic searches more difficult. Great 404 pages should help visitors find what they’re looking.

Here’s how I updated the 404 (not found) pages on my own site to resolve typos and suggest other pages potentially relevant to the visitor’s intended URL, in case you’d like to implement the same or similar functionality on your own site:

How my 404 page suggests alternate URLs#

If you were to click an invalid link or typo a URL on my site, the following would occur:

You’d see a 404 - not found page¹
Your browser would retrieve and parse my site’s sitemap.xml²
Your browser would find the valid path that has the shortest edit distance from the path you requested
Your browser would update the 404 page with a link to the suggested path

What it looks like#

Let’s say you tried to navigate to a path that doesn’t exist like /2022/06/30/unhelpful-404s-for-jekyll. Along with a list of recent posts, the experience, would look something like this:

The page you are trying to view does not exist. Perhaps you’re looking for /2022/06/30/helpful-404s-for-jekyll-and-github-pages/?

How it works#

This functionality is driven by a surprisingly small amount of JavaScript (really TypeScript):

import { closest } from 'fastest-levenshtein';

const div = document.getElementById('four-oh-four-suggestion');
if (div) {
  const xhr = new XMLHttpRequest();

  xhr.onload = () => {
    if (xhr.status === 200) {
      const xml = xhr.responseXML;
      const urls = Array.from(xml.querySelectorAll('urlset > url > loc')).map((el) => el.textContent);
      const url = new URL(closest(window.location.href, urls));
      div.innerHTML = `<a href="${url.href}">${url.pathname}</a>`;
    } else {
      div.innerHTML = '<a href="/">/</a>';
    }
  };

  xhr.open('GET', `${window.location.protocol}//${window.location.host}/sitemap.xml`);
  xhr.send();
}

The v0.1#

Could it be written better? Absolutely (but it works!). For now, I’m using fastest-levenshtein to find the closest path to the one requested, and the lower level XMLHttpRequest and querySelectorAll to retrieve and parse the XML sitemap.

Along with better error handling, this could also be implemented with the more modern fetch API to retrieve the sitemap and something like fast-xml-parser to more properly parse the XML, but my modern JavaScript knowledge is limited.³ If you’d like to take a pass at a better implementation, pull requests are always welcome.

Conclusion#

When I click on a broken link, the site that I land on should point me in the right direction. After all typo’d or updated URLs are not uncommon, and the site I’m visiting knows more about the site’s content and structure than I ever will. While it’s still true that everything should have a URL, sometimes those URLs change or get lost in translation. Although you might hope a visitor would never see one, great 404 pages go that extra step and help visitors find what they’re looking for. If you’re interested in implementing the same functionality on your own site, the code above is part of the retlab Jekyll theme, and is licensed under The MIT License.

When a visitor tries to access a URL that does not exist, GitHub Pages will serve the 404.html file in the site’s root directory, if one exists. ↩
Generated automatically by the Jekyll Sitemap plugin. The same implementation would work with any other static site (or static site generator), so long as your site has a comprehensive sitemap.xml. ↩
I’m proud to say that no jQuery was harmed in the making of this functionality. ↩

Ben Balter

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: amplifying judgment, not replacing it

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#

The PM as orchestra conductor#

Footnotes#

How to one-on-one

What belongs in a 1:1#

How to prepare#

How to run one#

Skip-levels: why they matter#

Anti-patterns to avoid#

The real test#

The brag doc

Nobody’s keeping score for you#

The ship log#

What makes a good entry#

Climbing Cringe Mountain#

Fighting recency bias#

Make it a habit#

No agenda, no meeting

Why this matters#

The thesis#

What to do about it#

Agentic workflows and the future of software development

From autocomplete to autonomy#

Building on what already works#

Why pull requests are the perfect interface#

A shift from writing to reviewing#

Trust but verify#

Making agentic development work for your team#

What comes next#

Footnotes#

I've worked remotely at GitHub for thirteen years: here's what actually works.

A company that rethought the defaults#

Using GitHub to build GitHub#

Open-source workflows for everything#

A hub, not a headquarters#

Intentionality over proximity#

The pursuit of an ideal#

What thirteen years taught me#

Footnotes#

How to run LanguageTool on macOS

Set up the local server#

One potential gotcha#

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

LanguageTool in Slack and other common work applications#

LanguageTool in VS Code#

LanguageTool in Safari#

N-grams#

Troubleshooting#

Taking it a step further#

Conclusion#

Footnotes#

The "I don't like what they're saying, so they shouldn't be allowed to say it" approach to crisis management

”Controlling the narrative” is counterproductive#

”Caremad” is a good thing#

The alternative#

Conclusion#

Footnotes#

Cathedral vs Bazaar People Management

Cathedral people management#

Bazaar people management#

Diagnose the situation, then pick your style#