 This is the general docs talk that we try and do every KubeCon to make sure that folks knowingly understand and try and care about documentation, generally, in the tech world. And specifically for the Kubernetes project, we think this is really important. So while turnout isn't always great, we're gonna keep doing this every year. And we're gonna keep trying to get folks to help us out. And that's exactly the topic of our talk today, that we want a lot of help in the documentation of the Kubernetes project. So I'd like to introduce ourselves. We are some of the special interest group for documentation for Kubernetes. My name is Natalie Vlatko, and my pronouns are she, her. I am an open source architect at Cisco, specifically with the open source program office. And I've been involved in Kubernetes for the last five years. And I am Davia Mohan. My pronouns are also she, her. I am a senior technical evangelist at Sousa. And like she said, we're both some of SIG docs and hopefully represent our SIG pretty well. Yeah, at the moment, we actually have, or very soon will be the Meet the Kubernetes contributor community group where you can come and meet all the other different SIGs and some of our other co-chairs and leads. And we'll be there after this talk as well. Yep. Okay, so looking at today's talk, the general theme is help wanted. Please help us, we want help. And we wanna direct you into the areas that the Kubernetes docs generally needs your attention and love and care. And so what we're going to be looking at today is learning about the Netlify build issues that we experience on the Kubernetes website, how we can, as a note, that we wanna be improving our proud utilization, which is the Kubernetes CICD system, how we want to improve our reference documentation generation, which is a real integral part of the project. And we'll talk about that in a little while, how we need help with web development, how an infrastructure projects such as Kubernetes does need web developers. And it's very hard to advertise that in a cloud native space, but we're going to try. And finally, how we also need help with some issue triaging as well. We're gonna go through how you can help and also then where you can find us. Right, but before we delve into that, let's talk a little bit about the scale and specifically the scale to which the Kubernetes documentation caters to. So we have around 1,30,000 plus pages as of today. And as we speak, there are probably a couple more added in that number. We have this spread across 15 different languages, including English. And we have, like Natalie said before, we have the reference docs as one of the subprojects, but we also have blogs. We have the different translations of the website and of course the main website itself where the documentation for the English localization is hosted. And our website caters to around 20,000 to 100,000 users per day globally. And all of this magic that you see is serviced, so to say by 2,500, around 2,500 voluntary contributors. Again, globally. Some more stats. We have three minor releases every year, as you'll already probably know, which amounts to around an average of 45 enhancements per release. And also, like with each release, we have blogs that come out, which are published and require reviews and approval. And that's around 12 blogs per release. And we also have reference docs which need to be regenerated because features change as pretty much everyone in this room can attest to. And we require a regeneration of these reference docs every release. So what does this mean? I mean, Rihanna said it best. So I'm not gonna say it. It's a lot of work, lot of work. And we are gonna delve into some of our pain points. And Natalie, do you wanna take it over from here? Yeah, definitely. We mentioned a couple earlier, but we'll just go over them again right now. The first pain point that we will, or one of the pain points that we have is reference documentation generation, which is something that is really under-loved and underserved in the Kubernetes project, despite being very integral to our releases three times a year. And it's something that we are desperately looking for help for, and not just help, but also people who wanna have autonomy and ownership over an integral part of the project like this. Another pain point is issue triaging, the amount of great, great people coming to read our documentation and then realizing something is missing so they open up an issue. But then that issue lingers because there's no one around to actually fix that problem, which is a great way for generating those issues, but we just then get a lot more work, and we don't know how to triage and bundle them up into work that actually should be distributed to the community. Now the pain point is web development. We mentioned it. How do you get web developers interested in cloud native? I don't know. I mean, we are looking to try and get a lot of help on the web dev side, more help than my atrophied skills can currently muster. And so that's another area that we'll be looking at later on. Netlify errors, this is something that I can- We've shamefully been postponing on this since I think last February. We've tried our best. We've gone through Netlify documentation, asked for support. We've debunked it on our own, but honestly, it just doesn't seem to go away. It's just like that persistent pain in your neck after a really wild night out. It's that. So that's one, and improving proud utilization is another challenge that we're looking to address. And if working with bots, so to say, is your strength or is one of your skill sets, please reach out. But we're gonna be delving into each or some of these in a bit. And I think Natalie's gonna take the first one with Netlify errors. Not my favorite topic at all, but we need to talk about it because we experience Netlify errors a lot. So let's go into some of the context of this. We use Netlify in the Kubernetes project to stage our, stage PR content. We use it across the entire project. It means that we use this to preview the changes that are suggested by a PR before merging it. And that is almost any kind of change. But also what we use that for specifically on the doc side is specifically around things when it comes to layout of our site diagrams is always a really useful thing to have Netlify preview on, generally how we're looking at creating new tables or things that are embedded on the site too. And also actually how the line spacing works, specifically for our localization teams, having the preview for that is also super useful. And so as Divya mentioned, as of February 2022, we've had some deployed previews are failing and this is one of the error messages that you can see with that. Divya was very, I would say generous with this slide because she said some deploys are flailing. I would say it's half and it's a huge number for us. And it's something that we have, as mentioned, tried to debug and we are just not Netlify experts. And so we are really feeling the impact of this. Documentation PRs take a lot longer because there isn't that preview. And then so there's a delay so we can make sure that what we're actually merging is going to look the correct way. It can also actually mask a real issue with a PR sometimes that if the preview fails, but there is actually something else wrong that we're not catching that the preview would usually help us catch, then that can also be an issue. And also actually it can show that checks have failed when on the Netlify side, but actually other checks are failing too when the Netlify failure masks the other. And that's something that is hard for us to actually discern. And then the email deluge. Oh my goodness, no one likes getting as many emails as we get about Netlify preview issues and Netlify deploy failures. And I'm about to show you what they look like. Divya, how many of these do you think that you get a day? I have a separate folder in my inbox for these because I get so many of them and we know that they're related to this. And we've been constantly trying to debug it. We've gotten all the experts or all the expertise that we have currently. And I can tell you that over the past one year we have around 20,000 plus emails. And that's not even exaggerating. I probably would be understating it at this point because I can feel my mobile vibrating right now and it could be another Netlify email that's coming through. Totally. So what needs to be done? We actually require help of someone diving in, hopefully maybe not concentrating on much other work in the Kubernetes project, really dedicated to diving in and finding the root cause of these failures and errors. And then we need a lot of help with testing because we really want to get this bug sorted. And then obviously the actual fixing of the issue. We're not looking for just one person. We do want folks coming in and working together on this and we are absolutely willing to, for even possible current contributors right now if you're listening on the stream and you think that this is something you'd like to work on, let us help triage or kind of get some of other contributors to take some other work off your plate if you're willing to come over and work on this because this is not going to be something that is easily fixed. It is a meaty, meaty challenge and we are really, really looking for your help. And who can actually be the people that help here? So we do need folks who have GitHub org membership of the Kubernetes project. It is going to be something where you're doing a lot of tests, putting in a lot of PRs that are going to hopefully try and help fix this issue and hopefully working with people who can review and approve your work and vice versa. So we do need someone who's already involved in the project or someone who's willing to become a member and get involved is also really worthwhile. Knowledge of Hugo, we definitely need this too, particularly the Doxy theme which is what the Kubernetes website uses and naturally, but we had to write it in case it wasn't obvious, knowledge of Netlify as well. So if you have two out of three of these things and you're willing to acquire the third, come and talk to us, we absolutely wanna hear from you. And just to add on to what Natalie said, the Kubernetes GitHub org membership is required because right now we get these emails and we have elevated access to Netlify. So if you are to troubleshoot all of these issues, you probably also will need elevated access and GitHub org membership from Kubernetes certifies that you have had consistent contributions over time and you can be trusted to work alongside us. This is why we require that and like she said, we are willing to help you if you are consistently contributing and helping us out or have helped out on other areas of the project, we're willing to help you get that. But again, terms and conditions apply. So let us know if this is something that is there and how do we get to, you know, how do you get to reach out to us? That's in the next slide. It is. This is the tracking issue for anyone who's interested in diving more into this issue specifically. We will make the slides available on Shed After as well so you can access it later. Divya's had a great work in putting a lot of the information in the tracking issue to help us get started with really pursuing this work. All right, take it away. Yeah, and Natalie mentioned that we have a lot of issues and by issues we don't mean personal ones, which we do, but we mean issues filed to the GitHub repo for the website. So currently we have 700 plus issues out of which 300 issues require triage. Now what does triage mean actually? We haven't gotten around to reviewing whether this is an actual issue relevant to the quality of the docs or the content that the docs contain or whether it's around the accuracy of the docs. This means that the request or the issue that has been filed could be literally anything and because we are so overloaded with the kind of issues that have been filed, we're not just able to get to the triage of these issues. So there are around 300 issues currently that require assistance in terms of triaging. And let's not even get to the backlog part because we have 100 issues in backlog, which means that they are triaged, they are open for contribution, but they are slightly lower in priority, which means that they haven't had much love. People aren't there to take care of them and get them allocated to contributors or contributors haven't actually reached out to work in them. So why and how does this impact us? Because if you have so many issues and if you see the Kubernetes website GitHub repo, we have incoming issues every day because every person would, I mean, if you read docs, it's generated by a human like you, except the reference ones, but that's also code snippets that are generated. So there's a human element somewhere there. And because there's this human element, there's definitely gonna be an issue with the docs at some point in your journey of consuming them. And these issues get filed, but there's nobody really to actually work on them. And the more the number of issues that are actually there, the more the actual issues that need to be worked on and are relevant to the Kubernetes docs, that actual surfacing becomes difficult. And I've seen several instances of these where contributors actually pick up an issue and they said that they wanna work on it, but it turns out that because it's not been triaged, it's not actually an issue relevant to the docs, it's actually a support issue. So we need help with triaging the issues, which means that we need help with the labeling of the issue, appropriate to the kind that has been reported, and also get the right audience to work on it. And of course, when you are saying that there are issues and when we're saying that there are issues, this leads to incomplete and sometimes technically inaccurate information within the documentation. And that's not what you'd want out of a project documentation that's so widely adopted and used. So that's how this impacts us. So what needs to be done? So for this purpose, we've introduced a new role within the Kubernetes website or rather sick docs known as the issue Wrangler. And what this issue Wrangler does is basically help with the labeling and outreach and socialization of these issues, as well as management of the issues in terms of project management, because that's something that we're not really good at, clearly. So we have introduced this issue Wrangler role to fit in just about the member role, which is the GitHub or contributor that we just mentioned a while back. So if you are already a GitHub or member within the Kubernetes organization and are looking to sort of, you know, start contributing to Kubernetes website, this probably would be a good role for you to take on after you've made a few contributions to K-Website because you would have more awareness about what kind of issues are filed to the GitHub repo, what requires labeling in a particular way, and all of that. So this level of responsibility comes in after the member and just before you start reviewing and approving PRs. Do you wanna add something, Natalie? We have also a short staff of reviewers and approvers too, but specifically part of the reason that we're so bad at a job like this is that because those of us who are reviewers and approvers are really concentrating on that aspect and are unable to use our time to do any issue triage or wrangling. So it really is about more bodies in the actual website repo itself to make sure that we can actually get work happening and moving throughout the project. Right, and again, who can participate? Like I just mentioned, this is not a good role for a person to assume right out of the, you know, if you're a big nerd, let's put it that way. If you're a big nerd, this is not a good role because you are probably not familiar with the kind of issues that are being reported to the Kubernetes website. You need to have that context first. So when you have worked your way around the Kubernetes GitHub membership and you have some knowledge about how the documentation process already works within SickDocs, this is a good role for you because you have some context, obviously. And these are our requirements. There's also a documentation in our Contributor Guide that lists these very, you know, requirements and you can check that out in our Contributor Guide on the Kubernetes website. And really, it's also given that you would need to work collaboratively because you're not gonna be the only person working on this. There will be a PR Wrangler, there will be an Approver and a Reviewer who will work around you. But that's a given, again, because you're working in a global project as well. Now, so if you wanna sort of nominate yourself and if you are interested and you have a GitHub membership, please feel free to scan the code. This leads you to an email that I've sent out for the nomination. Please read through the documentation and if you're eligible, this would be a great opportunity for you to sort of move your way up through the Contributor ladder. Okay, we're only gonna take 10 more minutes of your time, but this is definitely a media area that we wanna chat about now, which is our reference documentation generation. Now, Divya mentioned before that there is humans still behind some of this work, which is the folks writing the code that actually helps our auto-generated docs take place. And so what we wanna do is dive into a little bit of the pain points that we have here now. So for context, our reference documentation, it is a formal sub-project, but it's listed as one. And so we have this issue of there's no ownership of this very important aspect of the docs and of releases of Kubernetes throughout the year. That lack of ownership means, if everyone owns something, no one owns anything. It's that kind of unfortunate thing where no one feels responsibility or accountability for making sure that this part of the project runs as it should, other than maybe us as the leads of the documentation special interest group. But that is also something that we're trying to help out with in terms of finding folks who are willing and wanting to dedicate that time and that accountability space. It also actually requires a good knowledge of go for the tooling that helps generate these docs. We really do need someone who has very decent technical expertise and go to come in and drive a lot of this ownership. We do have some hopefulness with one of our tech leads, Chi Ming, who is awesome, and I just wanna say a shout out Chi Ming, if you're watching, you're great, who is going to help out with some of this, which is really great. But Chi Ming can't work alone. This is a huge, huge amount of work and we do need other folks who wanna come in and own this together and own that this is actually going to be working and running smoothly. The other thing that we do wanna mention, I wish we had a lot more beginner-friendly things to mention with what we need help with, but there was a steep learning code with the reference docs. I will openly admit, I don't know much about our reference documentation or the generated docs. And so we need someone who is willing to jump in and really learn the ins and outs of this part of our project. We've lost tech leads where that knowledge was in our project before, and this is why we're really, really struggling with this part of a sub-project that's not really one, but we're willing to turn it into one to get folks working and behind it. How does it impact us? The burdens of reference doc, it falls on very few people every release. Usually per release, it's one person, but we try and make sure it's a different person per release. And so that's three times a year, there is a bunch of work that really one person is having their door knocked on, saying, hey, please help, we need you to do this so that the release, it goes out on time. And of course, because there is that bus factor of one person, reviews and approvals take a lot longer. Even general issues when there's something wrong, we, I remember Divya, we had an issue with some of the generation a while ago, and it took a long time to solve because we just didn't have the people available to work on it. So what needs to be done? We as the SIG docs leads, we wanna help formalize and staff the sub-project, which is where we would help you. It's a work in progress, as I mentioned, as we speak, shimming one of our tech leads for docs will be involved, but again, we need a lot more people to come in and help. And our core for contributors to the sub-project is what this really is. We are looking for folks who want to come in and have a leadership role in an area of the Kubernetes project that is integral to every release and is integral to the entire project. It is something that is MIDI, that is going to be resume building, that is going to be something that will improve, not only your work in open source overall, but your general skill set because of how deeply technical this work is required to be. So please, please help us. This is our call to please help us. Who can help us? That is something that is a really, really great question. We need intermediate level plus proficiency of Go. We list this because we just wanna note that this is not a beginner project aspect. Like it's really not beginner. We do need folks who have a bit of time, thank you for the call, 10 minutes, a bit of time or a bit of knowledge that they're willing to sink in for the reference docs. It would be nice to have Kubernetes org membership. You will get it while working on this because of the work that you'll be putting in and myself and Divya will be the first two people to sponsor that membership once you're coming in and doing that work. So this is something, a part of a project that can actually help you get that org membership, get you involved more in other areas of Kubernetes other than docs as well. It's a really great opportunity. And it's also nice to have previous contributions to the Kubernetes project, but it's not required. Folks who are just out there interested in wanting to jump into Kubernetes for the first time with Go knowledge and you wanna help with docs, this is a great way to get started. And then that can also build the path to future contributions to other areas of the project or still in sync docs if you'd like to stick around. The tracking issue, again, big props to Divya, top documentarian of the year for the CNCF who has put together a lot of information about this issue. Feel free to scan this or follow the link for those watching on the stream so that you can jump in and look at the tracking discussion. We use GitHub discussions for this and for other areas of our SIG as well. So please come in and be part of the conversation. And last but not the least, we're gonna speed through on this one even though we have like eight minutes. So we're gonna leave some time for questions if you have. So the last area that we're gonna talk about is web development. And I know it sounds funny that we're talking about web development in like a cloud native conference but that's where we are. So the website obviously exists on the internet in the form of a web, like web pages in the form of web pages. So obviously there is some, you know, voodoo involved in terms of like Hugo and Netlify and stuff like that. So our project isn't very well advertised as being in need of web development help but it does a fun fact because as we saw in the previous couple of slides, nearly we have a lakh, one lakh, 30,000 plus pages that require actual rendering to website content and we utilize Hugo where actual web dev expertise is required and if you're a web dev looking to make an impact, SIGDocs is like one of that area where you could and shout out to the SIG Contrabex folks where I think Kate's contributor website is also an area that could benefit from the skill set. So what needs to be done is we basically rely on experts all across the project. We allow, we don't allow, rather we rely on our engineers to actually, you know, tell us more about the features that they're writing. So we obviously want you as the web devs to tell us where we could improve our website, whether it's design, whether it's the programming or whatever area that you feel is lacking within the website. We want you to have an opinion about it and let us know about that opinion because we want to enable our users across the globe to have a better experience of the docs when they actually consume it. So that's the, you know, only thing that needs to be done as like from our side, we are issuing a call for help here but if you are a web dev and you have knowledge, please, please reach out to us. And who can participate? Like for web dev experience, obviously you need to have like an intermediate level of proficiency with the languages. And also it would be good to have, it's not listed here but it would be good to have the knowledge of the Hugo theme, sorry, Doxy theme for Hugo because that's also how our Kubernetes website is rendered and it's using the static site generator. But Kubernetes GitHub org membership and previous contribution to Kubernetes, these are nice to have. These are not absolutely essential. We can help you get there like with the other areas if you are contributing consistently. So if this is something you're interested in, please chime in on our SickDocs or SickDocs blog channels and we'd be happy to help you. Speaking of blog, we do have a bonus area that we're gonna chat about Divya and very quickly we're gonna go through the need for blog reviewers and approvers. This is again something where for context, for folks who may not know, we have published around 50 blogs annually for the Kubernetes. A huge amount of those blogs also come around during release time. So there is a lot of traffic during the end portions of each release so that we can review and approve the release blogs that will be coming out and the different feature blogs that get written. But at the moment our blog sub-project only has four approvers slash reviewers and for those who don't know, you need an LGTM and an approve to people, to different people on any kind of PR that we work on in Kubernetes, but specifically in our blog project, we sub-project, we really do need two people bouncing off one another. Having only four actual team members who aren't available all the time, it's a problem. We are really, really short-staffed. I'm actually one of those who is hardly ever available and so it's one of those things that we absolutely need a lot more staff and a lot more support. How does it impact us, the backlog of blogs? People read the Kubernetes blog to find out how new features work and where they can start actually using them. They want to hear about the different deprecations that happen around Kubernetes or things that are going to impact the way that they deploy in their company. There's a lot of things that the Kubernetes blog is really important for, that we in the StigDocs group have to help ship it and push out for releases but generally across the whole time-loan of the project. But with only a couple of us, it leads to burnout, it leads to a terrible work-life balance, it leads to us actually being very absent of Pro-Wiz and reviewers, which means we don't put in the time and the effort needed to actually read and engage with the content that's going out and then the content becomes really sub-optimal and not really great. So what needs to be done, we need an increase in the stable pool of contributors for the Blog-Supp-Blog-Supp project and what that means is more reviewers and approvers. So more people who are willing to read and go through the blogs follow our style guide that we have in order to give those kinds of reviews to blog writers and blog writers come from all over the project and beyond. And we also need help initiating a shadow program to actually get those reviewers and approvers up-skilled. We want you to start this in an informal capacity. That would be great to help balance the burden, but we do want to actually formalize a shadow program for the blog so that we can get a lot more people coming in and less of the burnout of the current four team members that are working on it. I want to shout out to one of our tech leads, Tim Vanistar, who's already starting some of this process. Big thank you to you, Tim, and hopefully we can promote the contributors up the ladder around the blog. Who can participate? Org members once again, and that you must be willing to shadow and perform the role initially in an informal capacity. Divya. Right, and we're at the end of our presentation with this. So where can you find us? You have... This will be on shared, by the way. So we have a mailing list, and the bonuses that's subscribing to the mailing list actually gets you invited to all of our meetings automatically. So that's it. And you can also join us on the Kubernetes Slack. We are at SigDocs for all things documentation, of course. And we also have different sub-project-based Slack channels, which is SigDocs blog for the blog sub-project, as well as SigDocs localization for the localization sub-project. Now, when it comes to GitHub, it's the Kubernetes website repo for documentation and the blog and the localization. And for the reference docs, we have a Kubernetes 6 slash reference docs as the GitHub repo. So all of this is gonna be available and it's hyperlinked, so you do not need to worry if you cannot catch it right off the slide. But that is all we have for today, and we hope you had some idea of where you could start contributing and we invite any questions that you want. Yeah, and we may have to get off the stage unfortunately, but we're gonna hang around for a little few minutes so that we can take your questions one-on-one. Big thank you for coming. Docs are really important. We're gonna keep talking about it every year, so until people are sick of it. Yes. Thank you very much. Thank you very much.