Kubernetes Needs to Ditch GitHub

Oct 7 2017

The community has outgrown GitHub. And Drupal has a lesson for us. It's time to stop cobbling together a community from a host of free services, and it's time to build our own community.

The Problems

I have been working within the Kubernetes community for a few years now, and have watched it grow from a small close-knit community into one of the hottest open source technologies. The user base has exploded. The technology has rapidly evolved. But for some reason, when it comes to building an online community, we're still using a frustrating mishmash of "free" (as in beer) hosted services.

And at the core of this problem is the fact that Kubernetes still expects GitHub to solve its problems.

Before going further, I'll state this for the record: GitHub is a fabulous service. I have hundreds of projects hosted there, and I use it every day. But we all need to be honest: It is built for small-to-medium-sized projects. Kubernetes no longer fits the bill. It is unfair for Kubernetes to expect GitHub to do more, and unfair of Kubernetes to expect us to just cope.

Here are four problems, from least important to most important.

Problem 1: GitHub is not for complex orgs

GitHub has two layers of organization for projects: User/org, and repository. A project belongs to exactly one user/org. All permissions, project relationships, and communication tooling are based on these two tiers.

Kubernetes has already outgrown this model. Even with a huge set of GitHub "teams", organizational needs alone have extended beyond what GitHub can provide. And the "solution" to the problem has been to create multiple orgs that are all nominally Kubernetes orgs. So we have orgs like kubernetes, kubernetes-clients, kubernetes-helm, and so on. Their "officialness" is entirely unenforced (the org kuberentes-tacos, for example, follows the same pattern, but has nothing to do with Kubernetes).

With multiple orgs, we now have fairly complicated processes for setting up tooling, managing users, and so on. Much is done ad hoc or manually. And in exchange, we get all the added frustrations of this informal affiliation.

Furthermore, there is no way to grow a Kubernetes ecosystem that is both unified (easy for users to find) and open. Right now, a project is either official or totally outside of the Kubernetes organization. (I'll contrast this with Drupal's entirely open model later.) And what was once a single Kubernetes Incubator process has now fragmented by sub-project. In short, we're making a mess of the ecosystem because we don't have appropriate tooling.

Problem 2: Content is in Disarray

Looking for Kubernetes bugs? Check the issue queue. Looking for discussions about Kubernetes topics? Check the issue queue. Looking for proposals? Check the issue queue.

The issue queue is in danger of being a catch-all for all kinds of information. And at this point, it is impenetrable for mere mortals. Only people willing to spend substantial portions of their week culling the queue are able to experience comfort in the chaos.

So on one hand, too much is placed into the issue system. On the other hand, information like documentation and standards is scattered throughout various GitHub repositories, and is often difficult to find and work with.

And if you want to get involved with the community, your starting point is a vast GitHub repository which assumes significant insider knowledge before you can even figure out what all those directories mean.

But this leads us to a third problem. A substantial part of the content that communities generate simply does not fit inside of GitHub's source-focused model. So Kubernetes uses an array of other independent tools.

Problem 3: Backfill with Arbitrary Web Services

About a year and a half ago, Problem 2 began to hit the radar in one notable way: Users seeking help were "cluttering up" the issue queue with questions about how to use Kubernetes.

The solution: Send them somewhere else.

So Stack Overflow became the recommended way to get Kubernetes support.

The "send them elsewhere" pattern is increasing in the community.

Threaded discussions aren't supported on GitHub. So the Google-heavy Kubernetes contributors sent us elsewhere: To Google Groups.

And not all content seemed to fit well in the issue queue. So some got moved to Markdown documents stored in the GitHub repo, but others got moved to Google Docs -- neither of which are particularly good tools for the job.

Note that at this point, Kubernetes developers have to maintain at least three accounts: Google, GitHub, and Stack Overflow. And user names on these three platforms don't always match, which means it's hard to track who is who across the community.

Meanwhile, documentation is served as static files from GitHub pages, which means two things:

  1. There are no advanced CMS-like features. To edit, learn Markdown and Git and GitHub.
  2. Tools like search are provided 1990s style by a frustratingly clunky Google search page.

But wait! There's more! There's Slack, Zoom (and Hangouts), YouTube, Travis... service after service gets added to the Kubernetes "must use" list because GitHub doesn't have a rich enough set of tools for a behemoth project.

Problem 4: Disjointed User Experience

Now we arrive at what I think is the most critical problem: Kubernetes can't become a strong community because there is no unified experience of a community.

A compound effect of the above three problems is that the user does not get a clean experience. There is no central branding for Kubernetes. The official website looks much different than the GitHub project (even though the same content is available in both places). And this experience is different than Stack Overflow, Slack, and Zoom.

And the Google apps, like Groups and Docs, are jarringly different, as they are completely orthogonal to the others. Linking from a GitHub markdown document to a Google Doc causes a massive context shift from web browsing to word processing.

Here we are at the coup de grace: The willy-nilly context shifts are a roadblock to community-building.

At each context shift, the user loses navigation, information architecture, and visual continuity. The user loses both clear steps backward and clear steps forward. Log-in prompts interrupt flow. Site layout requires cognitive focus. And there are no environmental cues to say "this is how you stay in the Kubernetes sphere". Consequently, the burden of finding things is placed entirely on the user, unaided by the interface.

Even as a long-time member of the community, active 30+ hours a week for two years, I find it frustrating and time consuming to navigate around the Kubernetes ecosystem. How can we expect to draw in new people as the project complexity increases on a weekly basis?

If we stay using today's tools, we cannot solve this problem. And the community will suffer (or, rather, stagnate) because of it.

The Solution

The solution is actually quite straightforward: GitHub should not be the center of the Kubernetes universe. We need our own self-contained community hub.

Here's where we can learn from a far more mature project. Take a look at Drupal. One website serves as a massive community hub. It provides:

  • High-level information
  • Documentation, from installation down to API docs
  • Identity management, including authentication and authorization services.
  • Forums
  • Issue tracking
  • Ad-hoc sub-communities (SIGs, working groups, and user groups)
  • Git plus code review
  • Subprojects (Drupal modules, themes, etc)
  • Rich taxonomies for cross-linking
  • Integrated faceted search
  • Media, like images, videos, and animations
  • And then there are case studies, blog aggregation, job postings, conference info... all in the same place.

And all of this wrapped in a consistently branded, easily navigable user experience.

I can see right from the top-level page that they have 108,000 active users, 1,800 commits to Git, and 3,600 comments this week. 38,000 modules and 2,500 themes are accessible within a few clicks. In fact, almost everything mentioned in the list above can be found within two clicks from the home page.

Contrast this with Kubernetes. Can you get from Kubernetes.org to the official Kubernetes TypeScript client without using Google or directly typing a URL? How many clicks does it take you? Can you find the closest user group to your home? As a new user, how would you find out where to ask about DaemonSets? Can you find associated "non-core" projects like Istio or Draft?

And the killer is that it takes fewer people to operate the vast Drupal.org site than it does to manage Kubernetes' community tools. (Though, as an early review of this post mentioned, this site came at a substantial monetary cost.)

If Kubernetes cares about its users--if we care about the future of the project--it's time to up the ante.

GitHub isn't cutting it. And glomming on a dozen unaffiliated web services is not making anyone's life easier. It's time to build a real community hub.