KASLIN FIELDS: Hello, and welcome to the "Kubernetes Podcast" from Google. I'm your host, Kaslin Fields--

MOFI RAHMAN: --and I'm Mofi Rahman.

[MUSIC PLAYING]

I was checking out Kubernetes Reddit recently, and the top post was this GIF of a child trying to learn from a book by making a scooping motion on each page and dumping the knowledge into their head while they cried, with the headline, "Reading Through Official Kubernetes Documentation". On an unrelated note, on today's episode, Kaslin will be chatting with technical writer, Shannon Kularathna, about writing Kubernetes docs.

KASLIN FIELDS: But first, let's get to the news.

[MUSIC PLAYING]

MOFI RAHMAN: KubeCon NA is fast approaching. The schedule for KubeCon is out. If you are planning on going to KubeCon, you should also check out the Day Zero events. The co-located events span from Argo to Wasm.

KASLIN FIELDS: On its 10th anniversary, the distributed tracing project Jaeger announced a major evolution. It has been completely rebuilt on OpenTelemetry, resulting in the new Jaeger v2, which offers a more unified and flexible system. As part of this strategic shift, the legacy Jaeger v1 will be officially deprecated in January 2026.

MOFI RAHMAN: Kubernetes 1.34 is now available in GKE Rapid channel. This release comes just one week after the official open source 1.34 release.

KASLIN FIELDS: And that's the news.

[MUSIC PLAYING]

Hello, and welcome, Shannon. Welcome to the "Kubernetes Podcast". We're going to be talking about SIG Docs today. Could you tell me a little bit about your experience there, and a little bit about yourself?

SHANNON KULARATHNA: Yeah, I'm a technical writer by profession, so I currently work on the GKE docs, which is really helpful because it means that my actual day job is also super closely tied to Kubernetes. Yeah, and I've been contributing to the Kubernetes docs since right before I started working at Google, which was five years ago now.

I think I started contributing because I kept hearing that you need to have open source contributions to pass the interviews. And then I was like, OK, how do I do open source things? Because I didn't even know what open source was. And then, yeah, I found Kubernetes because as soon as I googled open source projects, the first thing was Kubernetes. And yeah, I started contributing to the docs because at that time, that was all I knew how to do.

And yeah, like, I really enjoyed it, just seeing the community and feeling like I was a part of something that's not just, you know, corporate interests. That felt really nice. So yeah, I've been doing that for about four to five years on and off with breaks in between.

KASLIN FIELDS: It's interesting to me that you posed contribution as a interview prep tool. I think that makes a lot of sense. It's really nice to have open source contributions to be able to point to when you're looking for jobs. And I feel like kind of the stars aligned there, if you're interviewing at Google and you're contributing to the Kubernetes docs, and now you're a GKE tech writer.

SHANNON KULARATHNA: Yeah, I think it really helped, actually, in actually getting the team that I got placed in. And it probably was because of the Kubernetes contributions. And yeah, like at the time, I didn't even know what open source was like as a concept.

KASLIN FIELDS: Really, who does know what open source is?

SHANNON KULARATHNA: Yeah, I feel like it's still a mystery.

KASLIN FIELDS: I mention often this book, "Working in Public" by Nadia Eghbal, which is about open source communities. And the biggest thing I learned from that book is just that open source is so different in other open source communities. I've only ever done open source contribution within Kubernetes, but when I talk to folks from other projects, it's very different.

SHANNON KULARATHNA: Yeah, and there's some really happy stories and I've heard some horror stories as well. And it feels very human where, like from person to person, you'll get very different experiences in people. And I think that's kind of what I like about it, but also scares me a little.

KASLIN FIELDS: It's very much a community, so it's all about working with people.

SHANNON KULARATHNA: I do appreciate that Kubernetes has very strict community standards, especially around respect and the code of conduct. I really love that.

KASLIN FIELDS: Yes, very important when you have a community of such a size.

SHANNON KULARATHNA: Agreed.

KASLIN FIELDS: There are all sorts of things that can happen. And in a sufficiently large sample size, anything that can go wrong will, as one might say.

SHANNON KULARATHNA: I feel like it's almost like, you know how the safety standards on construction sites? Like, each of those standards were put in place because something bad happened that needed a standard to prevent in the future. And I feel like I don't know if this is real, but I feel like Kubernetes must have gone through a lot to get to the point where it is now, where it's got such a robust code of conduct and such a respectful community overall.

KASLIN FIELDS: Yes, definitely. I'll try not to dive into that, as someone who works in SIG contributor experience, that is.

SHANNON KULARATHNA: Ah, yes, the keeper of the law.

KASLIN FIELDS: Yeah. Honestly, when I became a co-chair of SIG and [? Trabex, ?] that was one of the things that impressed me most about the previous co-chairs, is you'd come up with an idea like, why isn't the Kubernetes community doing this? They would have the lore. It's been tried. Now I am that person and I have to be very careful about discouraging folks' ideas with my lore of how it's failed before.

If you come into a SIG meeting and I tell you that we've tried that before and it hasn't worked, I'm not trying to say we shouldn't try it, saying that we should learn.

SHANNON KULARATHNA: Let's be cautious about this.

KASLIN FIELDS: Yes, but please, come to us with your ideas. We want to hear them. And speaking of open source work, so tell me a little bit about the types of things that you do within SIG Docs.

SHANNON KULARATHNA: When I started out, SIG Docs has a very straightforward contribution guide that really helps new contributors.

KASLIN FIELDS: It's almost like it's well-documented.

SHANNON KULARATHNA: Yeah. Actually, though, it was really good. And I think that was-- like, the Kubernetes docs were kind of my first exposure to large scale technical documentation that I actually wanted to read. And yeah, when I started off, I was mostly doing really tiny changes, either just commenting this looks good to me on like a tiny PR, or I would just go in, find a typo or something and try to fix that in a PR, and then eventually get told that you can't do these tiny changes without doing other changes, which is fine. I understand the point of that now.

But yeah, then over time, as I got a bit more confident in Kubernetes as like a platform and more confident in knowing where docs were, because there's so many docs, over time, I started to work on larger and larger changes. And then as time went on, and work fluctuating in busyness has led to me either doing a lot all at once-- so it's like bursts of lots of work, and then downtime where I'm not doing much contributing and I'm feeling a little guilty about it.

KASLIN FIELDS: Welcome to open source.

SHANNON KULARATHNA: Yeah, I feel like one of the team.

KASLIN FIELDS: That's one of the biggest things I tell folks when they're interested in contributing to open source is generally, open source communities are largely made up of volunteers. Even when it's related to your job or part of your job, very few people get to work on open source completely full time. You kind of do other stuff sometimes, at least, and that fluctuates. So folks are very rarely consistently active over a long period of time. There are waves where you're more active and then you're less active. And that's perfectly normal.

SHANNON KULARATHNA: Yeah, I think coming to terms with, like, I'm making my peace with that, I guess, is an interesting challenge.

KASLIN FIELDS: That is difficult.

SHANNON KULARATHNA: I was pretty jealous of the CNCF folks because, you know, actually, that's their job, right? They come in and help projects out with their docs, at least the tech writing component of CNCF.

And I remember feeling like, wow, these people are rock stars. They just waltz in and they just make this project do this cool thing, and then they just leave and they're gone. And I'm like, whoa.

KASLIN FIELDS: Impressive. So what kinds of docs do you work on day to day? I know we've got the release going on right now, which is coming up. I think we were talking earlier when we were prepping for these, about any work that you were doing with release-- release kind of has its own team that does a lot of stuff, but I think Docs takes on some of that work too.

SHANNON KULARATHNA: Yeah. So basically, when during the course of a release, feature owners who are working on creating the actual enhancements will also need to submit docs for that feature that they're developing for the release. And we have a pretty robust process in place for that where basically, they create a draft PR with the content that they want to add about their feature, and they open it up for review. And then SIG Docs' job there is to just go in, review it, make sure that it conforms to our style without getting too nitpicky about it.

And then, yeah, we review it, we LGTM it, and then it gets merged into the release branch. And then once the release actually happens, that branch gets merged into main and the docs get published. And so SIG Docs' main task is basically reviewing all of these PRs-- and there's so many of them for each release. It's reviewing all of those in time for the release to actually happen so that we're not blocking features from actually getting pushed out.

And there's different requirements based on what stage your feature is in. So if you're doing an alpha feature, for example, it's not as high of a priority for reviews, and it also doesn't need as comprehensive a set of docs as, say, a generally available feature, which makes sense because you never know.

KASLIN FIELDS: Yeah. There's such a wide variety of things that Docs covers do and reviews, always an underappreciated form of kind of glue work. We have a lot of problems with that in the community right now, that teams that I lead were also dealing with. In SIG Docs, there's also the blog subteam because kubernetes.io has the blog. So when there's features being released, you're obviously working on those docs. What other types of documentation work is within the SIG?

SHANNON KULARATHNA: The core documentation work is probably the how-to guides, the concepts, and everything that you see on kubernetes.io/docs. And then you've also got the blogs, which right now, from what I've heard, is very short staffed in terms of reviewers. But it's also like a low barrier to entry way to get started contributing because it's not as "technical documentation style"-- air quotes-- as the actual technical docs are, and it's a good way to get recognized in the community and also help out with a place that's currently going through a backlog.

KASLIN FIELDS: Make a big difference in the community. Consider reviewing blogs in SIG Docs.

SHANNON KULARATHNA: Please. And we've also got for each release, we've got the reference documentation. So that's all of the reference docs for the CLI tools like kubectl, kubectl. I don't know what the correct term is.

KASLIN FIELDS: I believe the canonical actual way that you're supposed to do it-- it was in the release notes for one of the release-- is kube control, but I reject that.

SHANNON KULARATHNA: Ah.

KASLIN FIELDS: I'm not going to say the whole thing out like that.

SHANNON KULARATHNA: I'm sorry, whoever created kubectl, I cannot--

KASLIN FIELDS: I like kubectl. I like kube CTL as well when I'm trying to be professional.

SHANNON KULARATHNA: Yeah, kubectl is just cute. It makes me think of, I don't know, for some reason, it makes me think of a crab just scuttling across the screen.

KASLIN FIELDS: Yeah.

SHANNON KULARATHNA: Yeah, but that's one thing we do is regenerate those reference documentation pages for each release. And then sometimes, if something gets missed or something gets pushed later on, just regenerating those. And we've also got very helpful release team people who shepherd everybody through all of these various moving parts and components of the release and make sure that everything's done on time. And they're the ones who come into our SIG meetings, for example, and update us about the status of the release and tell us if there's places that need extra love and places that are just good to go for that for each release.

And yeah, it's a very complex area, I think, just managing each release. But I think at this point, the processes have gotten to a point where it feels like it's running smoothly from the outside looking in.

KASLIN FIELDS: For now.

SHANNON KULARATHNA: It's like, dun dun dun.

KASLIN FIELDS: Everything is always changing in open source and there's always more to do. So like you were mentioning earlier, you go through these waves of being able to contribute more and having to contribute less to focus on other things. How do you balance your day job and working in the community? Any tips, any patterns that you found over time?

SHANNON KULARATHNA: I think one thing that really helps is just realizing that contributing doesn't have to mean like creating an entirely new doc set, or entire guides. It doesn't have to mean that at all. It can be something as small as going in and triaging the new issue backlog, right? Or it can be reviewing like a tiny PR and just unblocking it so that it can get published.

It can be even just joining in on community meetings and just sitting in and waving at new contributors when they join, right? And I just think that there's so many smaller but super impactful ways to contribute. And that has been one of the ways that I've tried to reframe how I think about contributing, while also being super busy at work. Yeah, so that's probably my main thing. And I've also tried blocking off time typically on a Friday, for example. And it's just called OSS. And I just do open source things, so that's been helpful.

Or I'll sit in on a SIG Docs meeting, like, during over lunch. I'll be listening in or something. And sometimes, I just don't have time to contribute, and I kind of have to make my peace with that.

KASLIN FIELDS: I think that contributing to open source is quite the way to develop skills of self-management.

SHANNON KULARATHNA: It is. It really is.

KASLIN FIELDS: Because there's such a wide variety of activities that you could do to contribute. Like you were saying, you can do something very small, just listening to a meeting, just review something like a triage session or whatever. Or you could own a whole project. There's a huge range. And the structures that are in place to help you are also led by volunteers. So I think interacting with open source over a long period of time, you develop skills around understanding how much you can actually put of yourself into something.

SHANNON KULARATHNA: It really does. And because you're volunteering your time and you're not getting paid for it, it really feels like you're doing something because you want to and not because you have to eat, if that makes sense.

KASLIN FIELDS: Which is very different.

SHANNON KULARATHNA: Yeah, yeah, it really is. And it also, for me at least, it has really helped with-- it has really translated well to work because open source has a lot more self-driven research needed, especially when you start working on more complex things. There's not really a central person that holds all of the organizational knowledge that you can go to and be like, hey, what's this thing? So instead, you kind of go digging yourself. So it's kind of like a little adventure, you know, you go digging into the source code and you see if you can parse things. Or you just you go through the docs and then maybe you find issues with those docs and you open issues in the docs project, but that's separate.

Yeah, so I think just that, yeah, it's been an interesting little adventure that has really translated well to my real life work at the office, basically. Because sometimes, I don't know.

KASLIN FIELDS: Yeah, that's a really interesting point around parallels between open source work and the roles in the tech industry that do similar things. I was actually talking with someone recently because I run the comms team in open source Kubernetes, which owns all of the social media accounts for the project. Some funny stories there, but--

SHANNON KULARATHNA: I feel like, tell me more.

KASLIN FIELDS: Oh, oh the stories. But I was talking recently with someone who is a professional social media manager or has been in the past. They moved on from that role, but I was asking for their help because I want to help more folks within open source Kubernetes understand how to interact on social media, how to create social media posts, how to contribute in that way.

And they were creating a guide for me based on their experience. And I saw a lot of what you were just talking about with tech writing is, you know, in open source, we're much more self-driven. We don't have as many partner teams to help us or, like, support kind of team relationships where you're working with another team who will do this part for you and you'll do this part.

You own things a lot more end to end, I think often, in open source. There's definitely, definitely collaboration, but especially in areas like tech writing and social media. Like, we don't have another team that's going to go make our images for social media or explore the whole of the project to figure out what we should be talking about. We've got to do all of that ourselves. So I think that's an interesting parallel between jobs versus open source roles.

SHANNON KULARATHNA: Yeah, and it really builds skills. Like, it builds that kind of independent thinking part of it. But at the same time, it teaches you about knowing your limits of, like, what you can find out on your own and then when to ask for help from a SIG. And it's really helpful, for example, if you've already done some digging and found some things, even if those ideas or thoughts are wrong, and then you bring that to the SIG in Slack or something, and you just ask them. And then, I feel like it's a higher baseline from which everyone can start giving you answers and helping you out as well, which is really nice, actually.

KASLIN FIELDS: You get a lot of that experience of working with other teams, because it's not like somebody's just going to go do the thing for you. You've got to go out and reach out and learn what other groups do and how you can interact with them on your own, so a lot of self-driven work.

SHANNON KULARATHNA: Yeah, a lot of people skills getting built as well, yeah.

KASLIN FIELDS: There are lots of skills we can build from contributing to open source. I talk to folks all the time who are interested in getting started as contributors, and I know SIG Docs runs a new contributor orientation itself. I actually run one for greater Kubernetes every month where we talk about here's how Kubernetes works, and here's how you might fit in as a contributor, just kind of at a high level across the whole project.

But SIG Docs has their own. And like we were saying earlier, Docs has really good documentation on how to contribute. So anything you want to point out about how new folks might get involved with SIG Docs?

SHANNON KULARATHNA: Yeah, I think the best possible way to do it is to join this Kubernetes Slack or whatever gathering place there is basically--

KASLIN FIELDS: Which is Slack, right now at least.

SHANNON KULARATHNA: Yeah. So, like, doing that is probably just the best way to get started, because then you start seeing messages in the SIG Docs Slack channel, and you see people interacting and talking about the docs, and you start putting names in. You start having names in your mind of, like, people who know more about this domain and that domain.

But if you don't want to talk to people, which is totally fine-- and I do that all the time-- is you can just go on GitHub and go on to the Kubernetes/website repo, and just go through the issue backlog. And you can look at an issue, see if it's something that you're interested in working on, and you can assign it to yourself and work on a fix. And all of the steps that you need to take to fix something in the docs are well-documented.

And even, like, if you think that that is also something that might be a step beyond what you want to do right now, you could even just read the docs. And if you see something that feels unclear, you could open an issue asking for clarity or asking for a fix to some errors that you've found. And that's a contribution as well, because you're helping to improve the quality of those docs.

And you could fix that yourself, or you could just have someone else will fix it. Yeah, so those are probably good ways to get started without it being too overwhelming, is just reading the docs, seeing if you spot typos or just tiny things that need fixing, or just going into the issue backlog and seeing if there are issues that you can work on.

And we also have a very useful issue type. We add the good first issue label to certain issues that are basically curated to be a low barrier to entry for first-time contributors. And we also have the help wanted label which we add to issues, which is a little more complex than a good first issue, but is still something that's approachable. And in both of those types of issues, you'll typically have support from an established member of the SIG or the entire SIG, really, to help you out with any questions that you have about authoring PRs or anything like that.

KASLIN FIELDS: You mentioned three things there, really, that I want to point out. I love that, number one, you mentioned lurking. Lurking is a great way to get started as a contributor.

SHANNON KULARATHNA: It really is, yeah

KASLIN FIELDS: Yeah. I tell folks in new contributor orientation that when you first start joining SIG meetings, you're going to be overwhelmed. It's all going to go over your head. You're not going to have any idea what they're talking about. And that's perfectly normal and fine. Like you were saying, what you're really looking to get there is to start understanding the terminology and how the group works and who is doing what, and you just kind of build that knowledge over time. Another point that you mentioned-- well, I'll go to the third one.

SHANNON KULARATHNA: Sorry, I feel like I spoke a lot there.

KASLIN FIELDS: No, that's great. Good first issues. Good first issues are actually something that I warn folks against a lot of the time, in a lot of areas of the project. I feel like SIG Docs is kind of an exception, though, because across the project, most of the time, folks who pick up good first issues never actually get them done. I don't know how much of a problem that is in Docs, but especially when it's like code that someone has to write, sometimes, folks pick it up because they don't know the language and they want an excuse to try to work on that. And that's more barriers to get over to get the thing done, in addition to the barriers of working in a community you're not familiar with, working with a review process you're not familiar with.

So a lot of people kind of get lost along the way. Even if it is a relatively simple issue that should be pretty accessible, there's still a lot of things that can throw folks off the train.

SHANNON KULARATHNA: No, I totally get that.

KASLIN FIELDS: Yeah, I feel like Docs is a little bit more approachable with good first issues, actually.

SHANNON KULARATHNA: Yeah, I think, at least from my experiences in working in Docs, the good first issues are more meant to introduce someone to the workflow of creating a PR and sending it for review and responding to reviews, than it is about something technical.

So typically, a good first issue will be something like two or three lines on this page are outdated, so here's what you need to do to fix this. So remove these lines, open a PR by following the instructions in this other contribution doc page. And it's just intended to teach this first time contributor about the workflow and the process of getting reviews and all of that, and then hopefully, that will give them the confidence in that ability now to go and tackle something a bit larger or something that interests them a bit more. So literally, just the first stepping stone into contributing.

KASLIN FIELDS: So if you're listening out there and you're interested in contributing, definitely check out SIG Docs. And I don't remember what my second point was, but join a new contributor orientation that happens once a month, and you'll probably hear it. Do you know when the SIG Docs orientation meetings are? Folks can find it on GitHub, I'm sure.

SHANNON KULARATHNA: Yes, there is a page on the Kubernetes website that has that as part of the calendar. I do not know when the contributor meeting is, but the SIG Docs meeting is biweekly on Tuesdays at 1:30 PM Eastern. And I've seen a bunch of new contributors show up to those meetings and also introduce themselves, because there's always a call at the start of the meeting by the meeting host, that if you want to introduce yourself and you're new to the project or you're coming back after a while, to feel free to do so. And that's always a super welcoming space to have. It's just emojis galore.

KASLIN FIELDS: That was actually the second point.

SHANNON KULARATHNA: Oh, perfect.

KASLIN FIELDS: I often tell folks, you should get into these meetings, introduce yourself, and start learning who the people are, because it is a community where you're going to have to work together with others. And the more the folks already involved there know who you are and what you want to achieve by being part of the community, the more they can help you find the right opportunities, and vice versa. You can also help them better and understand how to work with them better by learning about each other.

SHANNON KULARATHNA: I've specifically seen new people come in to those meetings and just ask, how can I get started? And then everyone's just super helpful in both with the actual voices and also over chat, just telling them where they can go to start doing stuff in Docs. I also just think that working in Docs is a really good way to learn Kubernetes as a platform.

So if you are interested in contributing to the code, but it's a bit daunting to you because there's so many different places that you can start contributing, SIG Docs is a good place to, you know, immerse yourself in Kubernetes as a system and see which area interests you. And you might find like a security doc interests you, or you might find that something to do with scaling interests you. And then you can start digging into that SIG and seeing where you can maybe help out upstream in the product itself. So that's a good way to wet your feet.

KASLIN FIELDS: So check out SIG Docs, consider becoming a blog reviewer and attending meetings. Thank you so much, Shannon, for teaching me about SIG Docs today.

SHANNON KULARATHNA: Of course. Thank you. I'm excited to see people join, hopefully.

KASLIN FIELDS: Yeah, join SIG Docs.

[MUSIC PLAYING]

That brings us to the end of another episode. If you enjoyed the show, please help us spread the word and tell a friend. If you have any feedback for us, you can find us on social media @KubernetesPod or reach us by email at <kubernetespodcast@google.com>. You can also check out the website at kubernetespodcast.com, where you'll find transcripts, show notes, and links to subscribe. Please consider rating us in your podcast player so we can help more people find and enjoy the show. Thanks for listening, and we'll see you next time.