Loading summary
Transcript89 lines
- [00:00]
A
Hello and welcome to the Kubernetes podcast from Google. I'm your host Kaslin Fields.
- [00:06]
B
And I'm Mofir Aman. I was checking out the 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, Kasdan would be chatting with technical writer Shannon Kularatna about writing the Kubernetes docs.
- [00:43]
A
But first, let's get to the news.
- [00:48]
B
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 Daisy events. The co located events span from Argo to OASM.
- [01:01]
A
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.
- [01:24]
B
Kubernetes 1.34 is now available in GKE Rapid channel. This release comes just one week after the official open source 1.34 release.
- [01:33]
A
And that's the news. Hello and welcome. Shannon, welcome to the Kubernetes podcast. We're going to be talking about sigdocs today. Could you tell me a little bit about your experience there and a little bit about yourself?
- [01:51]
C
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, okay, where is. How do I do open source things? Because I didn't even know what open source was. And then yeah, I just, I found Kubernetes because as soon as I googled open source projects, the first thing was Kubernetes. And yeah, yeah, I started contributing to the docs because that's at the point, at that time that was all I knew how to do. And yeah, like it. 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.
- [03:11]
A
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 here, contributing to the Kubernetes docs, and now you're a GKE tech writer.
- [03:40]
C
So 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.
- [03:58]
A
And really, who does know what open source is?
- [04:00]
C
I feel like it's still a mystery.
- [04:04]
A
I mention often this book, Working in Public by Nadia Egbal, 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.
- [04:25]
C
Yeah, like, and there's some really happy stories and I've heard some horror stories as well and. And it feels very human where, you know, like from person to person you'll get like very different experiences in people. And I think that's kind of what I like about it, but also scares me a little.
- [04:46]
A
It's very much a community. So it's all about working with people.
- [04:50]
C
I do appreciate that Kubernetes has very strict community standards, especially around respect and the code of conduct that. I really love that.
- [05:01]
A
Yes, very important when you have a community of such a size.
- [05:06]
C
Agreed.
- [05:06]
A
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.
- [05:14]
C
I feel like it's almost like, you know how the safety standards on construction sites like each. 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 had 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.
- [05:41]
A
Yes, definitely. I'll try not to dive into that. As someone who works in SIG contributor experience. That is.
- [05:52]
C
Ah yes, the keeper of the lohor.
- [05:56]
A
Honestly, when I became a co chair of SIG Contrib X 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.
- [06:23]
C
That's true.
- [06:24]
A
If I tell you, 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.
- [06:33]
C
Yeah, yeah, we should learn. Let's be cautious about this.
- [06:39]
A
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 sigdocs.
- [06:50]
C
When I started out, sigdocs has a very straightforward contribution guide that really helps new contributions.
- [07:00]
A
Like it's well documented.
- [07:02]
C
Yeah, actually though like it was really good and I think that was like the Kubernetes docs were kind of my first exposure to like large scale technical documentation that I actually wanted to read. And yeah, like when I started off I was mostly doing really tiny changes. Either just commenting this looks good to me on 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 like larger and larger changes and then as time went on and work like 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 just, I'm not doing much contributing and I'm feeling a little guilty about it.
- [08:27]
A
But yeah, welcome to Open Source.
- [08:31]
C
Yeah, I feel like one of the.
- [08:34]
A
Team that's one of the biggest things I tell folks when they're interested in contributing to open source is 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.
- [09:10]
C
Yeah, I think getting coming to terms with like, or making my peace with that, I guess, is an interesting challenge.
- [09:18]
A
It is difficult.
- [09:19]
C
I was pretty jealous of the CNCF folks because, you know, like, they're actually, that. That's their job, right? They, they come in and help projects out with, with their docs, at least the tech writing component of cncf. And I, I remember feeling like, wow, these people are rock stars. They just, you know, they just waltz in and they just make cool thing and then they just leave and they're gone. And I'm like, whoa.
- [09:44]
A
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.
- [10:07]
C
Yeah, docs. So sigdoc. So basically when during the course of a release feature, owners who are like 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 they 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 SigDocs 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 just, 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 Sigdocs main task is basically reviewing all of these PRs. And there's so many of them, right? For each release, it's reviewing all of those for 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 yeah, yeah, there's.
- [11:54]
A
Such a wide variety of things that docs covers too 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 are also dealing with. In SigDocs there's also the blog sub team because Kubernetes IO has the blog. So when there's features being released you're obviously working on those docs. What other types of like documentation work.
- [12:20]
C
Is within the sig we've got? 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.
- [13:05]
A
Make a big difference in the community. Consider reviewing blogs in sigdocs, please.
- [13:11]
C
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. Cuddle.
- [13:26]
A
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 kubectl. But I reject that. Yeah, I'm not going to say the whole thing out like that.
- [13:41]
C
I'm sorry, I'm sorry. Whoever created Cube Control Cuddle, I cannot.
- [13:47]
A
I like kubectl. I like cubectl as well when I'm trying to be professional.
- [13:51]
C
Yeah, yeah, 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.
- [13:58]
A
Yeah, yeah.
- [14:00]
C
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 this places that need extra love and places that are just good to go for each release. And that's. Yeah, it's. It's a very complex area, I think, just managing each release. But I think at this point the processors have gotten to a point where it feels like it's running smoothly from the outside looking in.
- [14:58]
A
For now.
- [15:01]
C
It'S like done, done, done.
- [15:03]
A
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?
- [15:25]
C
I think one thing that really helps is just realizing that contributing doesn't have to mean like creating an entirely new docset or like 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 a pr, like a tiny PR and just unblocking it from 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 Y things, so that's been helpful. Or I'll sit in on a SIGDOCS meeting during. Over lunch, I'll be listening in on something and sometimes I just don't have time to contribute and I kind of have to make my peace with that.
- [16:51]
A
Yeah, I think that contributing to open source is quite the way to develop skills of self management.
- [17:01]
C
It is, it really is such, such.
- [17:03]
A
A wide variety of activities that you could do to contribute. Like you're saying you can do something very small just listening to a meeting, just review something like, 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.
- [17:30]
C
Yeah.
- [17:31]
A
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.
- [17:43]
C
Yeah, it really does it like. And because you're volunteering your time and you're not getting paid for it, it. It really feels like you're doing something because you want to and not because you have to eat, if that makes sense, which is very different. 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 go through the docs with. And then maybe you find issues with those docs. Any 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, I. Yeah.
- [19:02]
A
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 the social media accounts for the project. Some funny stories there, but I feel like.
- [19:27]
C
Tell me more.
- [19:30]
A
Oh, the stories. Um, 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 like social media, like we don't have another team that's gonna 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. Yeah. So I think that's an interesting parallel between actual jobs versus open source roles.
- [20:47]
C
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, you know, 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, 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 them, bring that to the SIG in Slack or something and you just ask them. And then I feel like it's easy. It's a higher baseline from which everyone can start giving you answers and helping you out as well, which is really nice actually.
- [21:30]
A
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.
- [21:46]
C
Yeah. A lot of people skills getting built as well.
- [21:49]
A
Yeah, 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 sigdocs 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 sigdocs 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 sigdocs?
- [22:26]
C
Yeah, I think the best possible way to do it is to join this kubernetes Slack or whatever gathering place there is basically.
- [22:37]
A
Which is Slack.
- [22:38]
C
Yeah.
- [22:39]
A
Right now at least.
- [22:41]
C
Yeah. So like doing that is probably like just the best way to get started because then you start seeing Messages in the SigDocs Slack channel and you see people interacting and talking about the docs and you start putting names in like, 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 onto 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'd need to take to fix something in the docs are well documented. And even if, 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, you could fix that yourself or you could just have like someone else will fix it. Yeah, so that's. Those are probably good ways to get started without it being too overwhelming. It's 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 had to issue, which is a little more complex than a good first issue. But it's 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 to help you out with any questions that you have about authoring PRs or anything like that.
- [25:09]
A
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.
- [25:18]
C
It really is. Yeah.
- [25:20]
A
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.
- [25:52]
C
Sorry. I feel like I spoke a lot there.
- [25:55]
A
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 SIGDOCS 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. But yeah, I feel like docs is a little bit more approachable with good first issues, actually.
- [26:57]
C
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 priority 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 this page. 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 so 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'll 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.
- [28:00]
A
So if you're listening out there and you're interested in contributing, definitely check out SigDocs. And I don't remember what my second point was, but join a new contributor or orientation that happens once a month and you'll probably hear it.
- [28:11]
C
Yeah.
- [28:12]
A
Do you know when the SIGDOCS orientation meetings are? Folks can find it on GitHub, I'm sure.
- [28:17]
C
Yes, there is a page on the Kubernetes website that has that as part of like the calendar. I do not know when the contributor meeting is, but the SIGDOCS meeting is bi weekly on Tuesdays at 1:30pm 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. Yeah, it's just emojis galore.
- [29:00]
A
That was actually the second point. 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.
- [29:34]
C
I've specifically seen new people come into those meetings and just ask, how can I get started? And then everyone's just super helpful in both the actual, with the actual voices and also over chat, just telling them where they can go to like 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. Sigdocs is a good place to 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. It's a good way to wet your feet.
- [30:36]
A
So check out SigDocs. Consider becoming a blog reviewer.
- [30:40]
C
Yes.
- [30:40]
A
And attending meetings. Thank you so much, Shannon, for teaching me about sigdocs today.
- [30:45]
C
Of course. Thank you. I'm excited to see people join. Hopefully.
- [30:49]
A
Yeah. Join the docs.
- [30:50]
C
Yeah.
- [30:56]
A
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 Kubernetes Pod or reach us by email@kubernetes podcastgoogle.com you can also check out the website@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.