Skip to content

THE README PODCAST // EPISODE 31

Bridging code and community

Navigating open source in a regulated environment, the crucial role of non-code contributions to open source success, and lessons from scaling projects like Kubernetes.

Elapsed time: 00:00 / Total time: 00:00
Subscribe:
The ReadME Project

The ReadME Project amplifies the voices of the open source community: the maintainers, developers, and teams whose contributions move the world forward every day.

The ReadME Project // @GitHub

The influence of open source extends well beyond code. In this episode, we dive into the less-explored areas of the open source community, spotlighting their profound and wide-ranging impact. With host Neha Batra away for travel, Martin Woodward welcomes Kyler Middleton to discuss navigating the open source community in a highly regulated environment. She highlights the dual challenges of aligning cultural norms and overcoming technical barriers. Also, The ReadME Project’s Klint Finley is back to discuss the underappreciated importance of non-code contributions to open source projects. He emphasizes how roles such as marketers, graphic designers, technical writers, and community managers can be vital for the success of a project. Lastly, we feature a clip from our bonus episode with Kelsey Hightower highlighting the complexity of scaling a project like Kubernetes, which extends beyond technical challenges to include legal, financial, and community-related aspects.

Also on The ReadME Podcast

Kelsey Hightower—Present

Here’s what’s in store for this episode:

  • 00:00 - The hosts discuss the far-reaching impacts of open source and outline the symbiotic relationship between non-code contributions and OSS in everyday life. 

  • 03:02 - First Commit: How FarmBot is bringing automation to home gardening. Martin highlights how the open source community is putting a high-tech spin on backyard cultivation.  

  • 05:05 - The Interview: Kyler Middleton joins Martin to discuss everything from securing cloud applications to growing up on a farm.

  • 23:45 - #AskRMP: Kelsey Hightower on managing open source projects at scale and the learnings that can be applied to projects of any size.  

  • 27:42 - Feature Release: The ReadME Project senior editor, Klint Finley, is back to discuss non-code contributions and why developers should prioritize supporting their creation and management. 

Looking for more stories and advice from the open source community? To learn more from the authors and experts featured on this episode, check out:

Special thanks to Kyler Middleton for sharing her security and community insights, Kelsey Hightower for discussing open source at scale, and Sarah Rainsberger for highlighting the benefits of non-code contributions to open source success. 

Check-out The ReadME Project for more episodes as well as featured articles, developer stories, helpful guides, and much more! Send your feedback, questions, and ideas to thereadmeproject@github.com.


Martin Woodward: Welcome to Woodward World. This – this is the Martin Woodward Show. No, that’s rubbish. It’s the Martin Woodward Podcast and I’m Martinnn Wooodwarddd.

Neha Batra: Hey Martin. How’s it going?

Martin: Hey Neha. How you doing, didn’t see you there. Come on in, let’s get the show started. 

Neha: This is the ReadME Podcast, a show dedicated to the topics, trends, stories, and culture in and around the community. On GitHub. I'm Neha Batra and I lead GitHub's core productivity team.

Martin: And I'm Martin Woodward from the GitHub developer relations team. Hey, Neha, there's a phrase that Mark Andreessen made famous: “Software is eating the world.” Have you heard of that?

Neha: Oh yeah. I’m famils. 

Martin: Well, I've been thinking a bit about this recently. We can put a whole new spin on it. “Open source is also eating the world.”

Neha: Okay, aggressive. But explain that to me. What do you mean by that? 

Martin: Well, I've just been thinking there's so many ways that what we do, what the GitHub community does, it's not just building websites, building the libraries for other developers, whatever… everything we do impacts everybody's lives on the planet. There’s nobody that it doesn't touch.

Neha: Yeah, I mean, if I think about it, I know there's an impact in pharmaceuticals and in farming and in so many things. So in a way you can say that relying on software is relying on open source.

Martin: Right? So that's what I was thinking. I thought we could have a look at some of the hidden ways that open source and software in general is changing our lives.

Neha: And along those lines, I think there are a lot of ways that the less technical, less code-y parts of our jobs get overlooked, but they're also super important. So it's a bit of the flip side, right? Devs are influencing everything, but they also depend on solid communication, good writing, and a lot of other skills that make a symbiotic relationship.

Martin: Yeah, exactly. Which means on the show today we've got -- 

Neha: Actually, yeah, wait, Martin, I've been meaning to tell you I hate to do this, but I've got to hit the road this month. I've got family travel, conference travel. You know how it is. The good news is I get to do something that I know you love to do too. I'm meeting more devs from the GitHub community, but hey, you're going to do great. I can't wait to listen.

Martin: So I'm, I'm just doing these on my own?

Neha: Byeeeee.

Martin: Oh man, Neha. Okay, right. Okay, I got this. Well, today on the show you are in luck because you'll be hearing a whole lot of me apparently, and that's my favorite topic, but don't worry, we'll got some other great people for you as well, including Klint Finley on non-code contributions; Veradigm’s Kyler Middleton will talk to us about healthcare, privacy, and the cloud. And some bonus wisdom from our recent conversation with Kelsey Hightower. He talked with us about managing the inner workings of Kubernetes, including some of those non-code contributions that are so essential to successful projects. First up, it's first commit.

Throughout the show today we'll be looking at a lot of ways that open source feeds into a lot of things, and the key word here is feed. It isn't hard to think about those massive industrial farms with huge irrigation systems, automated machinery… they're all using open source, right? But what if I told you people were also using this kind of technology in their own garden variety… gardens? Enter FarmBot.

Robot Voice: I love to grow artisanal vegetables.

Martin: It's a system that offers hardware and software to create your own smart garden in your backyard. It's run a hundred percent on open source. It's not only more eco-friendly than buying all your produce at the grocery store. It lets you customize your garden as you'd like. There are motors, seeders and other handy things to help you grow all the plants you want.

Robot Voice: Yum. Open source carrots.

Martin: Plus everything you'd expect for an open source community like documentation, resources to build plugins, the ability to make contributions to all the open source repositories, all that meaty stuff or not so meaty, I guess vegetable-y, I don't know. Anyway, it's pretty cool that something like this can bring together technologists and traditionalists. Maybe they can even get together and break bread or maybe a nice carrot cake or something?

But be forewarned, it's all open source. So if your setup doesn't work quite right or you're not loving how your radishes have turned out, get ready to head to the FarmBot Community forum for help.

As we know from the kind of behind the scenes work that a lot of us do, developers and open source have a hand in all different aspects of life that many, many people don't actually realize. It's one of my things I really love about my job actually. It's not just the code part, but the human parts that we have impacts on. 

Today we're going to talk with Kyler Middleton. She works in cloud security in the healthcare space, an area where privacy and data protection is really fundamentally important. She's an engineer at Veradigm in the DevOps space, and we're going to learn about some of the tension she's been navigating in this kind of closed wall system around healthcare and sharing her knowledge, still, to help others around her. We're also going to be talking about some of the ways that she's been navigating the challenges that come with working in the cloud, in the healthcare space as opposed to working within the network on premises. So hey Kyler. Welcome.

Kyler Middleton: Thank you so much. I'm thrilled to be here.

Martin: So first, do you want to tell us a bit more about what you actually do at Veradigm?

Kyler: Sure. And that's a great question you and my manager have been asking me all the time. What do you do here? I am kind of a freelance DevOps engineer and I love that. I say freelance because I'm not on the DevOps team. I'm just the specialist that sits over in the corner until I'm needed. When projects have trouble, I come in and help, and help means solve technical challenges that have been befuddling the teams; help sort out processes and tooling; and just get things moving. Again, I find it really a lot of fun, especially when I teach everyone to do my job and then I step away and things don't explode. That's the best feeling.

Martin: Earlier in the show, we were talking about farming and you actually worked on a farm back in the day right? Before you got into tech?

Kyler: I did, I grew up in a very rural Nebraska in the center of the United States and you don't apply, there's, there's no interview. You're just the child of a farmer and you go to work because you live there and “if you want to keep eating in my house.” And it was just a ton of fun to grow up on a farm in wide open spaces and drive tractors and play with dangerous equipment, but there was no air conditioning. So here at computers I am.

Martin: Well, I live in the middle of rural northern Island surrounded by farmland with no air conditioning. So I certainly know how that is. How do you think the experience shaped the way you do what you do now? Seems very, very different working in healthcare to working in farming?

Kyler: It is, interestingly, exactly the same. When you're rural, you can't just head over to the Walmart to get something that you desperately need. The right tool for the job that which would be the Splunks or the Ciscos, the expensive tools that would solve the problem very, very well. You end up with just what you have in your toolbox and you need to repair it there. And in any regulated industry, there are significant rules around the tooling and the procedures and the processes. You can't just go post your code on the internet or post it with chat G P T and say, Hey, please solve this problem because you're in a lockdown environment. 

And it's very much the same as growing up very rural or trying to solve problems out in the country because you are very limited in the toolbox that you have. I love the open source community’s contributions because many of those tools I can use because I can audit the code base, I can use those things. So those open source tools are incredible for getting me started because they were low cost and building really cool stuff these days because I'm able to use them in regulated industries by and large.

Martin: And that's something that I think people who haven't worked in, say, healthcare or maybe some of the legal side as well. People in banks think they have regulation to deal with, but in healthcare it's a whole different ball game. It's a very, very regulated industry for good reasons. When I have a bad day, people can't compile code or people can't push code or something like that, that's a bad day for me. But when you have a bad day, there's like lives and people's privacy on the line. 

Kyler: Absolutely. I contracted for a while as a network engineer. That was my upbringing in the IT world before I get entered DevOps and cloud. And I was talking to one of the doctors on the floor of a hospital I was supporting and he was telling me, well, all the crash carts that revive people from death are Wifi-driven. So make sure the wifi stays up when you do that upgrade—like, lives literally depend on it. And that kind of pressure is something I have never forgotten. 

Martin: So what are the biggest challenges you actually see in the healthcare space? Is it around security and locking things down or what is it? What's the most problematic things that you're seeing right now?

Kyler: The answer is yes, among many organizations, many, many industries. The problem is you have to be totally secure and you also have to be totally fluid and allow your developers to innovate and experiment and test. You legally have to remain secure but in industry, in competition, in free markets, you’re required to compete quite strongly by innovation rapidly—so you have to do both, and that’s an impossible challenge. It's one that we do our best to solve, but it's a very difficult challenge to solve.

Martin: So how do you actually go about providing those guardrails so that developers and teams can innovate, but have the safety net so that they can do this in a secure way, but also do it in a way that they have psychological safety as well, because nobody wants to leak patient data accidentally. So how do you go about putting those guardrails in place for teams?

Kyler: I think I'll have an unusual answer compared to others. Okay. I think most techies, most engineers think in terms of tooling, you need the proper IM or rback controls. You need to secure your blast radius and your technical tooling needs to be perfectly managed, newest minus two versions, things like that. But I don't agree. I think it's training, I think it's people. The tools are rarely what leaks your data. You of course can be hacked by your public endpoints, but in a cloud environment, which increasingly is a hundred percent of the environments that I work in and help secure, almost everyone can see almost everything and they can touch almost everything. And you can certainly limit that technically. 

But I like to go the other direction. I like to train the staff to do a good job, and when they're empowered and confident that the guardrails are in place, the technical ones that let them experiment, they feel less psychological pressure to not touch it. You know, it works. Let's never touch it again. And when they feel safe, psychologically safe that the guardrails are there, they experiment, they build cool stuff. And I usually don't say stuff, I usually have to be bleeped on my conference calls, but I just like people to build cool things and they can only do that when they feel safe. So that's incredibly important. 

Martin: Yeah definitely. A buddy of mine called Donovan Brown used to say that DevOps was bringing the union of people, process, and products to deliver continuous value to our customers. And he deliberately put it in that order—people, process, and then technology—kind of thing because people's always the hardest part. And that's the slowest moving, the longest moving part kind of thing. And then the processes should be there to support your people, not the other way round. And then finally, the technology just underpins those processes and automates them and simplifies them. But unless the people are there and unless they're up to speed, then they can't do all that cool stuff that you keep, you mentioned. Yeah. 

Well, you mentioned cloud, I mean, and you are an AWS builder as well. So cloud and healthcare, that’s kind of… healthcare was some of the sort of slowest people to move to cloud because of all that regulation and cause of all the challenges that exist in moving to sort of a cloud way of working. 

So what challenges and opportunities do you think you should flag for people who are, you know, their companies kind of still getting into cloud or getting better at doing cloud software in different environments?

Kyler: That's the question. That's the driving question of maybe the past decade, as cloud has matured, is it worth it to use it yet? Is it still too scary and insecure for us to move our critical stuff to it? I have a consultancy and I talk to manufacturing, I talk to businesses that have trade secrets that might be sought after by other countries, by other businesses, and they're like, I've read that Cloud is insecure because those are what's in the news that S3 buckets are again, leaking data. Someone misconfigured a firewall and it's letting everything in. But that draw, that gravitational draw towards using this empowering tool set—which cloud is absolutely incredible in terms of empowering. I don't know if it'll save you money. I know that's advertised as the pitch. It'll save you cost and help you. I think it's more expensive, but it will empower the heck out of your developers to move fast and provision resources, provision configurations just incredibly quickly.

And that draw in terms of being competitive in an open market is huge. It can't be overstated because it is everything. So there's been a ton of pressure on cloud providers to please secure your things, use secure defaults. I understand it lets people move faster to turn off security, but really we need it. And even governments these days, there's a gov cloud for AWS are coming around. Even military secrets are now being put in clouds into public clouds. 

So I think we're there. I think we are. It takes some special training, it takes some understanding of maybe the weak points. S3 buckets have always been just overly complicated and leaking data sometimes. So you just have to know how to secure those. Anything that touches the internet should be carefully considered and architected. But things that are internal and don't touch the internet, you can feel free to experiment and build and break anything you need.

Martin: Now we're seeing more and more kind of open come into the healthcare space and into the networking side as well. You know, you spend a lot of your time working on close source kind of tooling and things for people, but yet you are still able, I see you online all the time, you're still able to share tools and share your knowledge with the community. How should people who are maybe in a more regulated industry, have you got any tips on how they can still engage with the open source community and with the developer community at large, even though maybe their day jobs is maybe fairly closed and locked down sort of thing?

Kyler: It's cultural challenge as much as it's a technical challenge. When I first started publishing blogs, I got that call from legal that you don't want to get that said, Hey, you're leaking our ip, this is our technology. We paid you a lot of money to build this. What are you doing? And I came up in the open source world. So I don't think about it as technology that's owned and these architectures and tool configurations and tools that I write, I think of as something that you should give back. I wouldn't be here without all the stuff that people published before me. So I want to help the people that come after me. So having that conversation with legal—that took many meetings and encouraging them to see that I can publish tools without compromising our security—was incredibly important and took a long time because legal is necessarily very conservative in terms of risk.

But eventually I got there. And that's just something that someone will need to fight within your own organization, that cultural fight with legal and risk and compliance, that you're not going to compromise your environment. 

And then technically, what can you rip out? How can you rip it out and publish parts of your environment without saying, we use this configuration that has this weakness, go for it. I'm this company, come find me on the internet. That kind of stuff is a technical challenge too. And I would encourage folks to start those conversations with legal. If you want to ask permission and not forgiveness and start working with someone who's done this before, what guidelines do they have for, what should you publish? What should you not publish? Because once it's on the internet, you can't get it back. It does not come back. So you need to be quite careful with passwords, with SSH keys, with secrets that might be related to your environment.

Martin: Well, and I guess that's one of the ways in which kind of public clouds, but also open source helps because by ripping out the proprietary stuff and focusing it on the public cloud endpoints you're using, or the terraform kind of scripts you are using to actually do deployments of things, it kind of makes it more reusable to people anyway and more applicable to their day-to-day.

Kyler: Absolutely. I, I'm a Hashicorp ambassador. I'm huge in Terraform. I love it. It's the best thing in the world. I love to just go read the Terraform documentation and learn how services work. I find it's a great way to get a running start on what is this tool called DynamoDB? Let's go look at all the resources that I can build and all the levers you can pull because it will tell you all of these settings can be customized, these three are required, these 10 are optional. That's what these do in one or two sentences. And versus reading white papers on how these things work, it's just absolutely incredible how quickly you can come up to speed and copy what other people have done. 

When you first start out in tech, you think, oh, when I'm a real programmer, I'll write everything novel, everything will be bespoke and all. It'll come out of my, I copy stuff from Stack Exchange about 40 times a day and I guarantee you all your seniors do, too. So go and copy code, go and try to understand what people are doing. And now that we have tools like Terraform, you can copy infrastructure configurations too and plop them down in your environments for testing.

Martin: Yeah, I find this a lot of times, oftentimes when people are using GitHub inside organizations, they're trying to bring that culture of sharing all inside of their company is very, very common. So we have enough kind of inner source conversations. And Terraform Scripts is a great example to me of why shouldn't we share these inside the organization, at least, because ideally, if it's correct, if everything's correctly written and I'm using say, volt, another product from HashiCorp, if it's published inside the organization, I gain no access that I couldn't already get inside the company on learning how that system's architected and being able to break into it. So why shouldn't I share these scripts around my organization? Cause it means I can go look at another team, see how they have configured something, how they're deploying something and learn from them. And then that way when I go have that meeting with them to go ask them questions, like the questions I can ask can be so much smarter and so much more informed based on sharing. And I guess the same's true publicly as well. It's sharing these scripts and sharing different patterns and ways of doing things is less about exposing secrets and more about just sharing knowledge and giving people inspiration to learn from. Is it?

Kyler: Absolutely. I was part of the cloud platform team at Veradigm for a couple of years, and I see these cloud platform teams popping up and it's kind of like DevOps. It's defined a little differently everywhere you look. But I think one of their primary jobs is cross pollination de-silo, those skillsets, de-silo those codes and modules for Terraform because you can empower everybody else in the company if you solve a problem, let people know that you solved it and share that code. Something that I recommend is an anti-pattern for a lot of company, which is putting all the terraform for every vertical, every different team within our organization, in the same repository. And then when poll requests come in for any team, everybody gets ’em. And that's an annoying amount of emails. But also you get to see what are the other teams working on?

What are the modules that they're using, what are the patterns and configurations and discussions that they're having, how are they building things? And then the whole point of that is let people copy. And I say it's an anti-pattern, it's not very dry, it's not very blast radius proof, but it sure as heck will get your network engineers and your database folks to start seeing what Terraform is and what it can do. If it can build 50 servers in two minutes, well surely it can configure a database too. It can build your VPCs and V nets and stuff like that. And those teams have been pretty reticent to adopt. Cloud databases are so sensitive, it's scary to touch them with automation. What if it does something I don't like? So getting them comfortable and secure with the tooling, seeing what other teams have done is huge. That's a great way to uplift and teach.

Martin: Now we're seeing kind of a massive rise in people doing network engineering, some of the more like the GitOps movement as well to a certain extent coming into open source and sharing their stuff in the open a lot more now. Any last bits of advice for somebody like you that's come from more of a networking space, getting into DevOps, getting into the cloud, where should people start and what should people go do? You must get asked this question all the time at conferences and things.

Kyler: I do because I think it's an uncommon background to have. I think mostly DevOps is developers that are far smarter than me at Java and Python and stuff like that, like writing code. And then systems engineers. I don't see a lot of database or network folks come into DevOps and really it's the same thing, focus on the basics. Everything still has an ip. There's still the concept of firewalls. They look a little different on a webpage versus an SSH to a Cisco router. But you're still filtering based on your tuple, your source dest and port or a laye- seven firewall that's filtering based on URLs and you're still routing, they're still B G P. A lot of that stuff is still relevant. So don't feel like, oh, it's the cloud, it's, it's a totally magical space. Those vendors will pitch you that their tool is magic and you don't have to know what an IP is anymore. You still do. You absolutely do. Routing is still incredibly relevant. DNS is still relevant, any of that fundamental knowledge, it's just a remix in cloud. It's been shuffled about, it has new names, but it's the exact same concepts you've come up with. So focus on the basics and you can go as far as you want to go. 

Martin: Well hey, Kyler Middleton, thank you very much for your time. It's been a pleasure talking to you today. And thank you for being on the ReadME Project.

Kyler: Absolutely. Thank you for having me.

Martin: Instead of a usual AskRMP this month, we are getting advice from an authority in this space, Kelsey Hightower. We spoke to him last month in a wide ranging conversation, but we specifically wanted to ask him about what it's like working on Kubernetes for so many years. What keeps that scale going in one of the most active GitHub communities? Here’s his advice on managing communities at this scale and what he learned that can apply to a project of any size.

Kelsey Hightower: When you get a project at the scale of Kubernetes, and there's a couple of levels of scale. One is like technical implementation, candid scale to from 100 notes to 10,000 notes. And there's the other scale of what happens when competitors all rely on the same technology. Now you need legal help, you need trademark help. You need to discuss what happens with patents, what happens with source code. You have to think about bad actors at the government level, people who have unlimited resources to put back doors into software.

And that stuff is expensive to audit at the depths. And so I think a lot of people don't understand that that's beyond what a solo maintainer or even a handful of maintainers are capable of doing, right? These audits are tens of thousands of dollars and different countries want different audits at different times. And so a lot of times I do think we have a love-hate relationship with foundations like the Apache Software Foundation or the CNCF. But when you think about it from a scale perspective, the community isn't only technical practitioners. The community now becomes lawyers and CFOs that are about to bet a huge part of their company on an open source project that if anything bad happens, you could actually bankrupt one of these organizations through something like this. So you end up having a lot more people join your community with different levels of concern.

So you have to have ability to think about the legal aspects, the financial aspects. Who pays for the testing infrastructure when the build is measured in millions? That is something that a lot of people don't think about, but it needs to be accounted for. And I think on the community side, I think the Linux community did a really good job. They have that concept of plumbers, they have a lot of documentation for new users and a way to pair program together to gain your skills because it's a very complex project. There are parts of Kubernetes that are very complex that probably less than 50 people in the world can work on. That's a very bad spot to be in. So you got to make sure that you don't lose anyone interested in working in those areas. So maintainers now become people who need to really spend a lot of time mentoring other people in their domain area of expertise.

And let's not forget those beautiful community managers. Those are the people who say thank you when no one else is looking. Those are people that are paying attention to the contributor graphs and noticing that there's not enough diversity in that graph. Those are people realizing that there does need to be a code of conduct because there is some bad behavior that's pushing away the very limited supply of people who can work in those corners of that project. And so all of these people end up creating what we call community. And so there's a lot of detail that goes into it, a lot of nuance, and we need equally talented people in all of those areas as we have people writing the course software that goes into the project. So you got to think holistically about this thing.

Martin: If you miss that full interview with Kelsey Hightower during Maintainer Month, head to github.com/read me to find it in our feed. Or you can head wherever you listen to podcasts. It’s episode number 30.

When you dive into the project, if you’re like me, you get all jazzed on the code. You want to see what people have done. You want to learn, you want to figure out how you can add your own spin or help the project be a little bit better. But we also know that all the other stuff outside of the code is hugely important as well. 

I once worked on a project called the Worldwide Telescope, which is this open source thing, which powers a lot of the planetariums that are used around the world and have you've seen some of the diagrams and space fly-throughs that you see on the news and science programs—that was actually done with this worldwide telescope open source application. And while the code and the client server sort of stuff was really important to making that work, actually most of the value in that particular open source project came from people contributing non code value to the community. So whether it's data, whether it's documentation, whether it's videos, sort of showing people how to use this amazing sort of worldwide telescope project. 

We're actually going to talk about non code contributions, things like documentation, education support, and community-building as well. To talk more about this, we have the ReadME Project’s senior editor, Klint Finley, back in the mix. Hey Klint, it's good to have you back.

Klint Finley: Always good to be here, Martin.

Martin: So why do you think people sometimes forget how important these non-code contributions are? Why do many of us, ya know, guiltily, just jump straight into the code?

Klint: Yeah. Well, I think it's understandable, and we do the same thing with commercial software. We think about software companies largely as the conglomerations of developers rather than these things that have all these other people involved, marketers, graphic designers, and technical writers and so forth. 

But in just the same way that a successful software company is going to have all these components, a successful open source project will have many of the same things. If you just throw your code out there and no one knows that it exists or no one knows how to use it or what to use it for, the project’s not really going to go anywhere. So these sorts of non-code contributions, especially documentation and just filling out a README file just are the keys to making something grow. And then as a project grows, you need to have community managers there to make sure the community doesn't turn toxic and just keep people on topic and keep a healthy community going.

Martin: Yeah, I've actually talked to a number of open source maintainers and they start off contributing the code, and then with the community, they actually get help with triage of bugs and things like that so they can stay focused on the code. Did you have a chance to speak to some maintainers about this?

Klint: Yeah, so I talked to Sarah Rainsberger, who's actually a core contributor to Astro, the web UI framework. But even though she's a core contributor, her main contributions are actually in the area of support and community. Here's what she had to say about it.

Sarah Rainsberger: I've heard people sometimes speak dismissively of PRs that fix a typo or fix a broken link. And yes, they are not code contributions. But if you, as an open source maintainer, as a project maintainer, if you care about your project being used by other people, then imagining the position of your user as they're trying to navigate your README or your documentation and the friction it causes when a typo is distracting or a broken link is frustrating. There are so many ways to contribute to the overall experience of the people using your project that don't involve code. It involves making them enjoy using your project, your product. 

Martin: I run into open source projects all the time where the documentation is less than stellar, really. Why do you think that is, Klint? What's happening there? What's going wrong?

Klint: Yeah. Well, I think documentation is the thing that I hear the most when I talk to maintainers in terms of what they would like to see more of from the community. And this may sound self-serving, coming from a writer, but writing is hard. And frankly, a lot of developers don't want to do it. They didn't get into programming because they wanted to write documentation. They got into it because they want to write code, they want to solve problems, they want to manifest their thinking onto the screen, which is of course also a lot of hard work. It's something they often just really want help with. And it's also really beneficial to have that outside point of view for writing documentation because when you've written the code, you how it works, you can forget some of the things that other people aren't going to know walking into it.

And it's also just a really good place to start in open source. You need to understand a project before you can really jump in and start contributing code or doing other things. So if you start by just reading the documentation, finding the things that are unclear, the things that need to be updated, you can start by fixing those things and contributing in that way before you jump in and try to do something else.

Martin: Well, Astro's a web framework. And Sarah's obviously very technical. I mean she leads Astro’s docs work as a core maintainer. She builds her own websites with Astro. So you’re seeing that people who are codes and have these technical skills—they’re still helping projects in ways that aren’t through code? 

Klint: Right. Yeah. So there are some non-technical ways that you can contribute to open source, say community management or graphic design. But a lot of things that are not code are still very technical. So release management is an interesting one to me, cause it's not something I often think about in terms of ways to contribute to open source, but as a project grows, that's definitely a task or a role that someone has to take on. And it is just a good example of where there's a need for very technical people to help out in ways that don't involve necessarily writing much code or any code. 

Support is another area. It's very technical. You need to understand the project, you need to understand how people are using it. In a lot of cases, you probably do need to understand even the underlying code. That's another really good place to get started with open source because you can get started right away just by answering people's questions with no poll request required, here's what Sarah had to say about her work doing support.

Sarah: I think of myself as being very close to what our users are doing. They are not trying to learn how to build a website platform or framework. They are trying to build a website. Are the docs written in such a way that when you type something in search, you are getting useful results? That's not a code contribution, but that absolutely is essential to people who are trying to code with our project.

Klint: And of course, non-code contributions aren't just for beginners. You really need to understand a project before you can make code contributions. So spending that time on documentation and support is a great way to get acquainted with the code base and with the community before you dive in and start making changes. And it's a good way to sharpen your writing and communication skills, which are important for any job. And beyond that, developers who engage with support will learn a lot more about how users are using a project, and start to understand where they’re coming from, what the applications are so they can actually write better code for the particular project. The non-code side is also just a good way to stay active in an open source community and sort of build a name for yourself. People are more likely to remember you if you stick around and respond to issues than they are if you just fix a few bugs and then never participate again.

And, as you said, Sarah is very technical, but she also makes the point that not only can coders contribute to non-code aspects of a project, but that getting started contributing to open source can be challenging even for experienced developers. 

Sarah: It can be quite overwhelming for people, whether or not you have a code background. People sometimes think that newbies to open source mean newbies to code, but that’s not the case. There are some really experienced devs who need help being walked through the process of actually submitting a poll request and what that looks like, how to commit a suggestion that they receive..

Martin: That's fascinating to hear, and I'm sure plenty of projects would love people to kind of help out in these areas. How do you actually go about attracting these types of contributions into your community in the first place?

Klint: Yeah, so I think one of the big ways is just letting people know the work that there is to be done. Lots of people want to contribute to open source and they don't know where to start. So marking some of these non-code related issues with “help wanted” or “good first issue” is just a great place to start. And here's what Sarah had to say about cultivating non-code contributors

Sarah: Astro, from the very beginning, from the top down, valued our community and our docs. Not all open source projects have a docs lead, but by showing from the top what is valued in the community—and I am one of the big peeps in the community, yet I'm just the docs lead—that shows what the project values, and that shows that your contribution will be valued because there’s someone there that you can see in an upper position who's being supported. 

We at Astro also happen to have a very tight docs and dev integration. So in short, one thing you can do is just value from the beginning things that aren't code. Value people who are in your organization doing things that aren't code. 

One of the other things we do is whenever anyone makes a first PR to the docs repo, we have a standard emoji template. We have this first-time contributor alert. We welcome a person in our Discord with a personalized message. They get a pun based on the title of their PR, and they are mentioned, and it goes out in our Docs channel and the entire community sees it. So Astro’s pretty good at recognizing and rewarding their community and making everybody feel good. We go a little bit over the top in Docs, and so it’s fun for someone to contribute to our docs, which is not necessarily code. Fix a typo, doesn't matter. You get the same red carpet treatment rolled out to you.

Martin: All right, well thanks Sarah, and thanks Klint. Speaking of documentation, I actually, I'm meaning to use Astro to go and rebuild my blog, so this has been quite inspirational for me. Thank you very much.

Klint: Thank you for having me.

Martin: Before we wrap up, Klint, what else is coming up on The ReadME Project? 

Klint: Well, Aaron Francis is back this month with a guide encouraging you to finish your projects. We also have a guide from Feross Aboukhadijeh with some actionable advice on mitigating open source supply chain attacks and proactively addressing dependency security. And Shanea Leven's guide explores a concept called "code visibility" as a solution to the familiar problem of maintaining aging codebases.

As always, you can find all of these articles—and more—on The ReadME Project at github dot com slash readme.

Martin: That's it for this episode of The ReadME Podcast. Thanks so much to this month’s guest, Kyler Middleton, Kelsey Hightower, Klint Finley, Sarah Rainsberger, and Neha Batra before she so unceremoniously left me. And thanks to you for listening. Join us each month for a new episode, and if you’re a fan of a show, you can find more episodes wherever you get your podcasts. Make sure to subscribe, rate and review, or drop us a note at The ReadME project@github.com. You can also learn more about all that we do at GitHub by heading to you github.com/reading.

CREDITS: GitHub’s The ReadME Podcast is hosted by Neha Batra and Martin Woodward. Stories for this episode were reported by senior editors, Klint Finley and Mike Melanson. Audio production and editing by Reasonable Volume. Original theme music composed by Xander Singh. Executive producers for The ReadME Project and The ReadME podcast are Robb Mapp, Melissa Biser, and Virginia Bryant. Our staff includes Stephanie Moorehead, Kevin Sundstrom, and Grace Beatty. Please visit github.com/readme for more community-driven articles and stories. Join us again next month and let's build from here.

Martin: Hey, Neha, you're never going to guess what actually happened today! Neha? Are you seriously gone?

Check out Kyler’s session at GitHub Universe 2023, on November 8! Grab your tickets now.

Meet the hosts

Neha Batra

Growing up in South Florida, Neha Batra has always loved building things. She dug into robotics in high school and earned a mechanical engineering degree, then jumped into a role as an energy consultant—but wanted a faster loop between ideation and rolling out new creations. Accordingly, she taught herself to program (through free online courses and through Recurse Center) and worked as a software engineer at several companies, including Pivotal Labs and Rent the Runway. She was also volunteered to make the world of open source more inclusive for marginalized genders on the board of Write/Speak/Code. Neha now lives in San Francisco, where she’s a Senior Engineering Director at GitHub designing products to improve the world of OSS. She’s also a foodie who’s into planning trips, and collecting national park magnets.

Martin Woodward

As the Vice President of Developer Relations at GitHub, Martin helps developers and open source communities create delightful things. He originally came from the Java world but after his small five person start-up was acquired by Microsoft in 2009 he helped build Microsoft’s tooling for DevOps teams, and advised numerous engineering groups across the business on modernising their engineering practices as well as learn how to work as a part of the open source community. He was the original creator of the Microsoft org on GitHub and helped set up the .NET Foundation, bringing in other companies like Amazon, Google, Samsung and RedHat to help drive the future direction of the open source platform. Martin joins the podcast from a field in the middle of rural Northern Ireland and is never happier then when he’s out walking, kayaking or sitting with a soldering iron in hand working on some overly complicated electronic based solution to a problem his family didn’t even knew they had.

More stories

About The
ReadME Project

Coding is usually seen as a solitary activity, but it’s actually the world’s largest community effort led by open source maintainers, contributors, and teams. These unsung heroes put in long hours to build software, fix issues, field questions, and manage communities.

The ReadME Project is part of GitHub’s ongoing effort to amplify the voices of the developer community. It’s an evolving space to engage with the community and explore the stories, challenges, technology, and culture that surround the world of open source.

Follow us:

Nominate a developer

Nominate inspiring developers and projects you think we should feature in The ReadME Project.

Support the community

Recognize developers working behind the scenes and help open source projects get the resources they need.

Thank you! for subscribing