On Kubernetes, human languages, and building open source communities

Kubernetes is a big project, and there’s a lot of documentation. Some of it is relatively straightforward, and some of it is painfully complex. Suppose that documentation is written in a language that you don’t understand—even the basics would be out of your reach. You would find yourself in the difficult position of having not only to learn a complex new technology, but to do so with only your best guess as to what might be going on. That’s not exactly a recipe for success—and it’s a real scenario that untold numbers of technologists face every day around the world.

But thanks to a small but dedicated team of volunteer translators from around the world, that documentation is available in a number of other languages, which is an important part of making the project accessible to as many people as possible. At Scaleway, we are proud to count two of those volunteer translators among our ranks: Benedikt Rollik, and Rémy Léone, representing the German and French-language translations teams, respectively. They were both kind enough to answer some questions and share some thoughts about their respective experiences as contributors to the Kubernetes documentation.

Let’s start at the very beginning…

Both of them proposed their first pull requests in the first few months of 2019—within weeks of one another, in fact. This sort of thing doesn’t just happen by accident, and I wanted to know more about what motivated each of them to jump into the project.

Rémy:
My first inspiration was to learn a bit more about Kubernetes, and to help people that struggle with English to understand the many complex concepts that are present in Kubernetes. I also wanted to push a good French translation into the zeitgeist for concepts that sound ugly when they are said in Frenglish.

Benedikt:
Same as Rémy; I wanted to get a deeper knowledge about the concepts and the way Kubernetes works. Also, translating very technical content requires you to understand it well in order to be able to produce a quality result.

Part altruism, and part self-improvement—this is a powerful combination and one that drives many open source contributors across the world. Helping others whilst also helping yourself is an easy win-win proposition, and one that sits at the heart of the most successful open source projects.

But, like everything else, what motivates a person at the outset of an adventure isn’t necessarily what keeps them going day in and day out. For a project as vast and as deep as Kubernetes, there is an enormous amount of documentation, and simply not enough people to translate it all. So for Rémy, it’s about efficiency—about using an engineering mindset to try to maximise the outcome of his actions.

Rémy:
There are so many pages to translate, and while I don’t mind doing benevolent work for multi-billion dollar corporations, at the end of the day I’ve got a day job to do, too. Therefore, I’ve used analytics tools to assess the Kubernetes website, and dump the 100 most-consulted pages. Most people need the same information regardless of language, so that’s where I can have the most bang for my buck.

Frugality is also the name of the game for Benedikt. With only three people in the German-language team, they have to work with a laser focus on impact. In this case, they aid and encourage the larger community to contribute translations, and direct their time and efforts into reviewing those translations. In other words, they perform an essential quality control role, ensuring that the documentation meets the high standards they set for themselves.

Benedikt:
We rely mostly on community contributors for now as we don’t have all the time required to translate such a huge project with the limited resources we have. We focus on having only the most important information up to date and translated. Personally, I review translations, but I also proof-read things like blog posts which may be written directly in German to begin with.

This is a solid strategy for any distributed, volunteer project: focus first on quality and impact, and the rest should fall into place.

Putting the work in

The vast majority of public, open source work today is managed or in some way tied into GitHub, and the Kubernetes project is no exception. But while GitHub is undoubtedly a good place to deal with pull requests and bug reports, many conversations take place on the official Kubernetes Slack workspace. As Benedikt notes, “I interact with the community on Slack and via GitHub on their PRs,” which is similar to how many businesses and organisations around the world handle their interactions and division of labour.

The work itself can take many forms. Translating and quality control are certainly big parts of it, but that’s only part of the equation.

Rémy:
At the moment I mostly help other language teams to get started. I introduce them to the [official Kubernetes] Slack and provide a bit of mentoring—not for the language obviously, since my Vietnamese, Portuguese, and Ukrainian are all rusty—but I like helping people that are a bit lost to find their way more quickly.

Having community leaders within the project whose role is to help bring new contributors up to speed is so important no matter how large or small the project is. New contributors often bring strong energy to the project, and finding ways to focus that energy into early wins is a key part of nurturing a positive, productive, and ideally long-term relationship with the community.

Another part of building that long-term relationship is ensuring that the amount of time and effort that any one individual expends isn’t excessive. The translation and localisation work remains a volunteer initiative, where most—if not all—of the contributors have other things they fill their professional, personal, or academic lives with. In this case, Benedikt does “one to two reviews per month as well as about one [translation]”, with Rémy pointing out that “the work is quite well spread among the other maintainers.”

But, why?

Building a solid culture and keeping tabs on workload are important, but at the end of day, people also need to understand the value of their contributions. We’ve talked a lot about the “how”, but what about the “why”? For example, as technologists, why engage in translation instead of coding?

Benedikt:
Documentation needs to be clear and precise, and written in a way that is understandable to different types of end-users, and to both power users and beginners—as well as as by machines! So it is important to think wisely about the words we use to describe complex technical processes and concepts, in a way that is both precise and as universal as possible.

The scenario described by Benedikt is profoundly complex, and one that requires a broad and deep understanding of not only the technology, but of human nature as well. Language forms and is formed by the cultures and societies around us, and is in turn shaped and shaped by the people that employ that language. What assumptions can one make about the reader—about their background, about the cultural, technical, or academic references they’ll know? And to make things even more complicated, the documentation might not even be written for a human in the first place!

In other words, it’s the very definition of a hard problem, and it is absolutely the sort of challenge that drives a certain type of person—a person like Rémy, who adds further insight into the complexities of the issue.

Rémy:
Consider that both code and documentation are meant to be mainly read by machines—compilers for the first, search engines for the second—and only eventually by humans. In order to provide the right amount of context, and to help it all make sense to the end-user, we need good structure, lots of metadata, and deliberate interconnections between pieces of content.

It’s difficult work, but it’s also rewarding personally, professionally, and communally. It’s an open source project, but it’s also an open source community—one that Benedikt is proud to be a part of.

Benedikt:
The work in the project has helped me to improve my skills in writing precise technical documentation for a tech-savvy audience. The Kubernetes user base is a very active community full of friendly people—exchanging best practices and getting feedback is a good way to keep me motivated, and it keeps me willing to continue to learn and to improve.

All of these things, from the onboarding, to the workload, to the organisation, to the culture, and so forth, don’t somehow exist by magic. Good communities are constructed. They’re nurtured. They build and adhere to principles and codes—in other words, governance. With a clear understanding of how everybody is expected to function and interoperate, and a way of helping and encouraging people to operate within that framework, the possibilities are endless.

Rémy:
In the end, what matters was the friends we made along the way. Some people have moved on to other adventures, but many have stuck around. I’ve learned that you can interact positively with a large community—if it has good governance, which is the case for the Kubernetes community. There is so much work to do—but it’s good work, and especially useful for students or beginners, because they can learn new stuff and do something useful that will give them visibility.

Recognition is important

When it comes to translation work, this is very much a case of “behind-the-scenes” labour that can be thankless. So I’d like to take this time to thank—publicly, and without let or reservation—both Benedikt and Rémy, and the rest of the volunteer translators, for helping to make technology more accessible and available to the world. Keep fighting the good fight!

p.s. If any of this sounds interesting to you, the community would love to help you get involved with the project!