Skip to main content

The Zen of GitHub

3 min read
: 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.

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 words 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 as to 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 are 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.

Originally published August 12, 2015 View revision history
Share

More to explore

Why everything should have a URL

15 min read

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.

An open letter to government CIOs

3 min read

Government CIOs don't need bigger budgets or more staff. They need to build lean, iterate quickly, and embrace open source as a way of working.

Removing a feature is a feature

8 min read

Features aren't free. Every time you remove one that doesn't serve your core use case, you're adding an implicit feature that does.

Leaders show their work

10 min read

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

Ben Balter

I'm Ben Balter — I write here about engineering leadership, open source, and showing your work. I was the Director of Hubber Enablement at GitHub, where I helped thousands of GitHubbers do their best remote work. Before this role: Chief of Staff for Security, enterprise PM, and GitHub's first Government Evangelist. Before GitHub: attorney, Presidential Innovation Fellow, and member of the White House's first agile development team. More about the author →

Follow along: Bluesky LinkedIn

This page is open source Help improve this article on GitHub