Skip to main content

The Zen of GitHub

3 min read Written while I was at GitHub

Summary: Whether you call it taste, culture, or zen, there are underlying assumptions that members of an organization rely on to resolve ambiguity in pursuit of the organization’s mission. Write yours down: culture gets a lot less squishy once it has a URL.

I’ve got a broadside hanging in my office which reads “ZEN” in bright red, hand-typeset lettering. It’s what we call the Zen of GitHub. It’s the first thing displayed each time a GitHub server spins up, and it’s the philosophy that has historically underpinned most major decisions at GitHub, both technical and otherwise. I can’t take credit for writing it, but @kneath, its author, published a great write-up on the how and why that GitHub Zen came to be. Speaking to the contrast between Apple and Microsoft, he wrote:

[A]n organization’s taste is defined by the process and style in which they make design decisions. What features belong in our product? Which prototype feels better? Do we need more iterations, or is this good enough? Are these questions answered by tools? By a process? By a person? Those answers are the essence of taste. In other words, an organization’s taste is the way the organization makes design decisions.

Kyle uses the term “taste”. In government, we often call it “culture”. Whatever you call it, it’s the underlying assumptions that members of an organization fall back on as they resolve ambiguity in pursuit of the organization’s mission. Should we be iterative or precise? Process driven or outcome oriented? Do we serve end users or execs? Spoken or unspoken, these assumptions will undoubtedly shape what the entirety of your organization’s outputs are optimized for, so why not write them down?

At GitHub, we did just that:

  • Responsive is better than fast
  • It’s not fully shipped until it’s fast
  • Anything added dilutes everything else
  • Practicality beats purity
  • Approachable is better than simple
  • Mind your words, they are important
  • Speak like a human
  • Half measures are as bad as nothing at all
  • Encourage flow
  • Non-blocking is better than blocking
  • Favor focus over features
  • Avoid administrative distraction
  • Design for failure
  • Keep it logically awesome

These aren’t mere words. There’s an API endpoint to retrieve random Zen (as seen live above), should you ever need it. Whether you’ve written them down or not, whether you’ve discussed them or not, whether you’ve realized them or not, every decision members of your organization make is bound by the constraints of these (often unspoken) first principles.

If you haven’t already, I’d encourage you to spend a cycle documenting those assumptions that drive (or constrain) your organization’s efforts. You’d be surprised how much less squishy culture becomes when culture has a URL.

Keep reading

  • Leaders show their work

    Great leaders don't just communicate decisions. They explain how and why. Without that context, every decision sounds like "because I said so."

  • Why everything should have a URL

    When knowledge lives in people's heads and inboxes, it doesn't scale. Giving decisions and processes URLs makes context discoverable, async, and opt-in.

  • Manage like an engineer

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

Ben Balter

I'm Ben Balter, and I write here about developer platforms, product and engineering leadership, open source, and showing your work. I spent over a decade building developer platforms at GitHub. For five years I was a product manager for trust and safety, shipping 500+ features and the API endpoints behind them to 50M+ developers. I also led a bottom-up rewrite of GitHub Pages and wrote the open source library behind GitHub's license detection, and my open source projects have hundreds of millions of downloads. I wrote Open and Async, the playbook for remote and distributed teams, and shipped a Model Context Protocol (MCP) server alongside it so agents can query it directly. More about the author

Follow along: Bluesky LinkedIn

Originally published August 12, 2015 View revision history

This page is open source Help improve this article on GitHub

Keyboard shortcuts

Search

  • / or ⌘ K Open search
  • ↓ or j ↑ or k Move through results
  • Enter Open the selected result
  • Esc Close search

Go to

  • g then h Home
  • g then p All posts

This page

  • y Copy link to this page
  • ? Show this list

Turn off if you use voice control or keep triggering them by accident. ⌘ K still opens search, and this list stays under "Keyboard shortcuts" in the footer.