 Hello, I'm Tim Bannister, and this session is Introduction to Kubernetes Docs. I'm joined by Celeste Horgan, Evie Aini and Brad Topol. So in this session, we're going to talk about the Kubernetes website, the group that maintains it, how to add or update documentation for Kubernetes features, a little bit about how docs happen in the release cycle, how to localize your content and where to get help when you need it. At the end, we're going to be around and we're going to try and spend plenty of time answering any questions that you have. So as I mentioned, this is the Kubernetes documentation special interest group. We maintain the Kubernetes website at ks.io. Now, the main thing that that documentation provides is that website provides is documentation. And the documentation is categorized into several broad areas. First one I want to talk about is concepts. High-level overviews of topics. There's also tasks and tutorials. So these provide detailed step-by-step instructions explaining how to accomplish a specific outcome. There's a reference section along with a glossary of terms used in Kubernetes. You'll also find details about the Kubernetes API and the binaries that make up Kubernetes, how they work, their overall purpose, their command line options, and that kind of detail. I also want to mention that this website is localized into already 13 different languages. English is the upstream localization, but there are 12 others. Ivy's going to talk about that more later. And localizing content is just one way of contributing. I want to mention why the documentation for Kubernetes is a really important way, I think, of contributing to Kubernetes. Because documentation is, you know, as much as code delivers features, documentation drives adoption of those features by making them accessible to people who are not already involved. And so if you're interested in contributing to the documentation, your work there helps make Kubernetes accessible to a wider audience and indeed might help bring on more contributors in the future. In terms of the technology, the Kubernetes website is a static site generated using Markdown from code that's on GitHub, like a lot of Kubernetes projects. It's on GitHub in the Kubernetes organization. The repository is called Website. Markdown is similar to plain text, but you add extra highlighting, for example, with these asterisks or underscores. Basic Markdown also offers lists, hyperlinks, code snippets, and a few other things. I'll talk more about how we extend plain Markdown to add additional features in a bit. Before then, I want to talk about some different ways to contribute, so let's going to talk about that in detail. If you're wondering where to start, SIGDOX curates a list of good first issues. We've identified these as a good choice for making your first contribution. And when I say first contribution, that could be that you're new to Kubernetes at all. You've not contributed anything, but it could also mean that you're actually someone who's contributed to code already or another part of the organization. You've not contributed to the documentation website. So in either of those cases, these good first issues are for you. We've got this list, and if you want to get started, you're very welcome to pick up one of these labeled issues, look for the good first issue label, find that and make that your first contribution, so that we're trying to give you an easier route as possible to getting started. Now, if this is your very first contribution to Kubernetes, there is some sort of paperwork. It's online, but paperwork to get through before we can review your PR and move it forward to getting merged. We need you to sign a contributor license agreement. There's two ways to get this signed, depending on whether you're signing as an individual, or whether that actually you're associated with an organization that has signed as a corporation. In either case, you can open a pull request, but then what you'll find is that some automation checks whether you have signed the CLA. Now that check is by your email address. So it's important to make sure that the email address that you're using in your Git commits matches up with the one that's used to check your CLA status. Now you see that details link that you can click on the right highlighted there. That takes you to the page on the Linux Foundation website that you can use to sign in, check your CLA status, and also to sign up. We're going to talk more now about Markdown and some of the technologies we use to get the website built. So on top of Markdown, we use Go templates, and the particular format of Go templates we use is Hugo templating. Hugo is an extension of Golang's built-in templating that renders static sites for you. The Hugo tool takes the whole set of Markdown source code and a set of rules and works out how to build the pages. The theme that we use for that is called Doxy, which we've customized moderately heavily to look like the Kubernetes website that you see today. And to make all of that work, we've got some automation around pull request on GitHub. I'll talk about that. We've got a tool called Prowl, which is used not just in the website repo, but across Kubernetes. Some of you will be really used to it. For others, this might be your first encounter with this robot. Prowl merges PRs when they're marked as looks good to me. I'll talk more about what that means later. They're approved and they're not held for some action to happen. But actually, after you submit a PR, the Netlify tool, which hosts the website, does a complete build of the whole site based on your changes. If you've got a PR, you'll see that a comment turns up on that PR. See the arrow? Linking to a preview. You can click on that link. And what you'll see is basically it looks like the same website. The URL is a bit different. And so this is a version of the website that you can click on to check if your code is okay. And it's also what reviewers will look at if they want to make sure that your changes are valid. Now, if you want to get some extra credit, what you can do is you can go and find the page that you changed in your PR. Now, Netlify doesn't do this for you. So it's nice if people do this. Find that particular page, dig out the link and add a comment to your pull request. Saying this is the exact page you changed and maybe like this is the original page. And if you do that, you're making life easy for reviewers and approvers by letting people directly compare your changes. Anyway, I'm going to talk about the process of getting the website built. As I say, it uses Netlify. So starting from the point when you've actually proposed a change, maybe you're going to fix a spelling mistake on the website. Unlike some other code changes, like a one word fix can be a valid contribution. You've opened a pull request. So GitHub tells Netlify that you've done that. Netlify builds and publish that preview version I mentioned. At the same time, the Proud tool makes sure that you sign that contributor license agreement and starts tracking review and approval status. Proud does a few other things. For example, it'll work out what languages you're contributing to and add a suitable label. So a reviewer will have a look at your PR. If it's technically sound, in other words, you've put in some changes. They make sense. The markdown is valid markdown. There's no egregious violations of the style guide. More on that in a bit. And it matches the PR description. Then the reviewer adds an LGTM label. The approver has a different job. Approver's job is not to verify your changes technically. It's to look at that PR description and just agree that that changes an appropriate one to make for the website. But once both of those things has happened, the PR is ready to go forward. If it's a small change like fixing one spelling mistake, often one person can do both of those roles. Now at this point, Proud will see that the PR is LGTM and approved until GitHub to merge it. GitHub merges your pull request and Netlify sees that the master branch is updated, builds and deploys the website. This is a continuous deployment process. So once that main branch is updated, your change is alive. So to be clear, this isn't anything that has to wait for the next Kubernetes release. Your change is alive as soon as they're merged. There is a separate branch process. It's relevant if you are contributing features that don't need documenting it quite yet. If you're making changes for a future Kubernetes release, find the development branch instead and put your changes on that branch or propose a merge into that branch using a PR. Don't worry if you're not sure, reviewers will help you find the right target branch and sort that out. Okay, I'm going to hand over to Celeste now who's going to talk about how to get started and about writing good documentation. Thanks Tim. So as Tim mentioned, the high level overview is that you create a fork, you make some changes and then you open a pull request. We're going to back up a little bit and talk about how to make the changes that make it into that pull request. So typically, as Tim mentioned, we work on local forks of the documentation repo. Nobody can create branches directly against main unless it's for a release or a translation. So you're going to pull down your local fork onto your computer and then you're going to run two commands. Make container dash image and make container dash serve. So we deploy Hugo locally into a container because here in Kubernetes land we love containers. But it also gives us a consistent environment to build against, which means that what you see locally is going to reflect what's going to build in that automatic preview that Tim mentioned earlier. So once that builds, you can access the website on your computer at localhost 1313. Next slide please. One thing you keep in mind is if this is your first contribution, we do load in the doxy theme as a sub module. So you will need to pull in the doxy theme and its dependencies using the get sub module update command to the very first time you run it. You'll run into errors otherwise. So this is really important. Next step. So when it comes to like doing a contribution as a whole, we think that everybody is welcome to contribute to documentation. There isn't a baseline level of technical skill needed other than being able to wrangle Hugo and get. And contributions from all different levels of technical skill are super, super welcome as well as contributions from people speaking other languages. So the majority of our contributions happen in English, but as we're going to talk about later, there's about 13 different localizations of the Kubernetes docs and they all need contributions as well that are equally valuable. There's really detailed documentation on how to contribute to documentation on the website. So check out the section title to contribute on your spare time. Next slide please. So as Tim mentioned, we do have a documentation style guide and what the style guide lines out is things like capitalization rules and grammar rules and words that we try to avoid and words that we try to use instead. And in general, we do a check for any egregious errors against the style guide. So take a look when you have a chance. The other thing that the style guide is great for next slide is word things like Hugo short codes that we use across the site to do special things like note and warning blocks and other things to enrich the documentation experience. We welcome contributions to our style guide as well. So if you think that there is a rule that our documentation should be following in terms of language and grammar, please feel free to open up an issue in regards to that so that we can start the discussion. Next slide please. So in terms of getting going with your first contribution, the first thing to keep in mind is that we are here to help. And the best thing that you possibly can do is to ask for help. For the most part we're very available via Slack and SIG docs and SIG docs localization. We also have a mailing list Kubernetes SIG docs and if you join that you get an automatic invitation to the weekly SIG meetings on zoom. They occur I live in Vancouver so in my time zone they occur in at 1030 on Tuesdays most weeks. And I believe it's about five or six UTC. Another great way to get started if you can't make it to to the SIG meetings and zoom and Slack isn't going to work out for you. Take a look for good first issues in GitHub. We are generally very good about tagging those next slide please. Most contributors to the Kubernetes project are not technical writers by trade however I am and as are a few other people on SIG docs. And so I wanted to take a moment to talk about just have a good documentation for people who are writers by trade. The first thing to keep in mind is that all writing contributions are valuable to SIG docs. You'll see below an example of a one word change to documentation. In other SIGs that might be viewed as a bit of a spammy change but for us that's super valid because that actually corrects the grammar of that sentence and makes the documentation easy to understand by letting the language get out of the way. So edits and type of corrections are incredibly welcome as a rule we kind of like it if you're going to if you're going to submit an edit maybe edit the whole page and not just one area. New content is super super welcome and we feel that developers are the people to write that content by and large. But also if you are a writer by trade or just very comfortable with English language we really really welcome editing and reviewing PRs because a lot of the contributions we get from developers are not by people who have English as the first language. And they do actually need that help with grammar to bring up the quality of the documentation. Next slide please. If you're taking out a big new documentation task, just some general tips for writing well. First off, break down what you're writing into the smallest sections possible. It's really really hard to say I'm going to document stateful sets. That's a really really big thing to talk about, but it's easier to think of it in terms of I need to introduce stateful sets as a concept or something that's explained at a high level. Then I need to explain to people what tasks they can do with stateful sets. Like adding or removing them. And those are step by step instructions or tasks. And then I'm going to provide a table of reference of any flags or options that you can set on stateful sets that are useful to to know as a piece of reference for people who are working with them actively. And those are called reference tasks. So I think breaking it down and then understanding the different categories of writing is a really good strategy. I personally find writing in bullet points first, and then translating those into full sentences very helpful. And as the lead tech writer at the CNCF Zach Coralyson often says, always be deleting. Try to be as brief as possible and to write and then delete a whole bunch down. Next slide please. A few last tips. Write in the present tense so I am or the stateful set does rather than I will do or the stateful set will do. Or in the past tense, I won't or I was doing the stateful set was in general keep sentences short. Use plain language when possible avoid complicated words. And there's a great app called Hemingway app. It's free. It's online and it automatically scans anything that you put into it for complicated words and sentences that are too long, and I highly recommend using it. And finally ask for help and sick docs because there are technical writers hanging out in there. Next slide please. So, once you've made your wonderful well written it first request which are going to do is you're going to commit it and then open a pull request as Tim stated against Kubernetes website. So here's where the PR Wrangler comes in. So the PR Wrangler is a approver in sick doc so somebody who is fairly high up the contribution ladder. And on a weekly rotation one person in that list is assigned to look at the PR is that week and approve them for content. So these are people who are going to provide you detailed feedback and suggestions. They're going to put that approved label on your PR so that it can get merged. If you're writing something fairly technical these are the people who will flag down the appropriate sake to make sure that the information is technically accurate. So the rotation for that is on the wiki and now I'm going to hand this over to Irvi who's going to talk about localization, the blog and next steps for contributing. Thank you so much. So here are in stick docs we have different kind of groups and one of them is localizations. So what's the difference between translation and localizations. While in translation we translate the whole page from one language to the others. In localizations, we try to make sure that the content of this page is appropriate when we translate it into the other language. So it's more like adapts the message into the local audience of the language that we will translate it into. And in these subgroups we try to tackle some kind of common problems for each of the localizations team. For example, if let's say one localization have team have problems with how to sync the branch between the master upstreams and their own branch. And the other team is having the same problems we will try to kind of discuss whether we have kind of solutions for this kind of problems. Or other teams have already have the solution for this problem. Next please. And here we have 12 localization teams as of today. More teams are of course will come. Next please. And there is a common procedures on how if you are want to add a new localizations. So the first important thing is make sure of the code of your ISO language. And then you can take a look into this PR here. There is an example of how France at their locations. And then there is also a content on how you can localize your content from the upstream. Of course English and then you can try to localize it into your your own language. Next please. And there is a golden rules on how you can submit your PR for localizations. It is make sure that when you stop with your PR it is for one language. And of course there is exceptions for this kind of PR. For example when we create a release branch that branch for specific release. And we try to sync with the master branch. There is changes from different localizations included in that PR. And but but it's it's also applicable because that's the process that we have on when you're trying to create a release branch. The other example is when we switch the whole site into dot C. And another example here is the security notice for a certain features. Next slide please. And there's also another sub projects here which is lots. So there is several guidelines for this sub projects when you are trying to start with your blog post. The first one is the article should be applicable for our users. So it shouldn't be a specific on vendor. However, if you are not sure because there is a delicate balance, you can try to reach out the blog team to check whether your article is still appropriate for blog posts or not. And the article are not published on specific dates, since it will be reviewed by a volunteer and it might take time to review the content. And if it's more like strict in the terms of schedules, you might consider talking to the CNCF marketing. And it should be an original post and aim to be future proof since the Kubernetes has a high velocity development and try to plan to cover long term technical content. You can check the blog on the link that provided here. And of course anyone can write the blog post and submit it for a review. Next please. So here you can try to contribute by filling an issue like suggesting a feature or reporting a box. You can of course add log error whenever you submit a bug report. You can also help with web designs, reviewing pro requests, localizing existing pages, writing new content. And of course you can also help by improving existing contents, adding tags or diagrams. SickDocs in general uses Kit and GitHub. You go and identify to make it all work. You can edit pages and open pro requests directly within GitHub website. And if you are suggesting changes, you can preview them locally first. Next please. If you're looking around, if you like, it's okay to fill of a web at first. And you can try to ask some help. You can try by starting smalls to help you get an idea of who is working on what. What paths are underway and what's on the roadmap. Next please. So how can we get in touch? You can try to sign up for Slack in the Slack.KayateAce.io and drop by in our channel in SickDocs. And there's also different kind of channels for our subgroups, which is the sick-docs-localizations and sick-docs-log. Come and say hello. Feel free to ask questions. Next please. You can try to take a look into our GitHub. And see good first issues here. Try to join our Google groups, the Kubernetes SickDocs. And by joining that, you can get invitation to our weekly meeting. You can drop by and say hello here. See Slack for details. No, I will hand this offer to Celeste. So we wanted just to thank everybody who attended this talk. And we hope you learned a lot about documentation. Believe it or not, this is a very high level overview of what the SIG does. And there's a lot more that we could go into. So all of us will be available after the session for a Q&A. And we hope you'll join us there. We also hope to see you at our weekly meetings and in the SickDocs channel on Kubernetes Slack. So thank you very much and have a great day everybody.