 Hi everybody, welcome. I'm Jim Angel. I am part of SigDocs. I've been a co-chair for SigDocs for a little over a year and been involved with it a little bit longer than that. And so today what I'd like to do is go very, take the deep in the deep dive and go very deep early on and let's talk about the technology stack that SigDocs is using. And then I'm going to hand it over to Chris to go into a little bit more into contributions, how to contribute to SigDocs and how to be a effective member of the community. And then we're going to pass it over to Brad to help us wrap up and talk a little bit about our localization efforts. So starting off, who are we? We are SigDocs and we run the kubernetes.io website or k8s.io. And with that, the Kubernetes website serves about 1.3 million users every single month. It's pretty incredible. And you can see here on this first slide we do have a few of our popular pages called out, Judging by Traffic Monthly. So before we get started, like I said, I wanted to go deeper into the technology. And this is one of the common asks that we get as part of SigDocs is how does Kubernetes do documentation? What is the actual thing that makes the docs real? And so while I am going to go deeper into the technology here, the specific technology isn't important. It is understanding that journey from start to finish and how those pieces all come together. So my goal is not to go into every single little detail on how the Kubernetes website is published. But my goal is to give everybody in this room a little bit more further literacy when it comes to Kubernetes documentation. And so when you go to the Kubernetes website, you actually know what you're looking at. You can see how the things are operating and understand the overall process to get started more effectively. So the Kubernetes website is hosted on GitHub. It is all in code. And right now this looks like any other screen grab of GitHub. And so we're going to get a little deeper into what does each one of these folders, directories, and the structures mean. Before we get further, we want to talk a little bit about Markdown. So those who aren't familiar Markdown is a way of writing specific features that represent the HTML counterpart. And so what I mean by that is you can see there is four asterisks down the side here about what Markdown has to offer. Those four asterisks win generated with a static site generator, which I'll talk about more in a second. It will take those Markdown files that are just plain text, generate them and create HTML files. So what you're seeing here is the Markdown non rendered version. And we'll kind of compare those as we move forward. So I mentioned all of the magic happens with a static site generator. There's a handful of them out there. There's Jekyll. There's Hugo and a handful of other ones all serving the same purpose. Give me Markdown. Give me HTML, Partials, layout, short codes, mash them together. Give me a static website. So really this is allowing folks to take the different subsections of the docs, write Markdown for the specific sections, and then write a general HTML template that can be generated to create the website. So I mentioned Hugo. Hugo is the engine that we're using to generate our static websites. And when I'm learning a new technology, I need to know what the thing is. You know, what are we talking about when we talk about Hugo? At the end of the day, Hugo is written in Golang. It's a Go binary. You could run it in a container. You could run it as a binary on your host system. The idea of being Hugo is that magic power that we just showed here where it's taking your Markdown is jamming it with HTML is creating your beautiful web page at the very end of the day. And it's all written in Go. So the few key points here is extends Golang built in templating for organizing and building the website. All content is contained in Markdown files. And then it is a binary at the end of the day that can be used in many different ways. So Hugo out of the box knows of a certain directory structure that it looks for. So if you try to run Hugo anywhere in your computer system today, it most likely is going to fail. Now if you give it this directory config, where you have the arc types, you have config.toml, and you have a few of these different components here. If Hugo sees that, it understands where and how to render each page. So breaking down the various directory structure of Hugo here, we have arc types, which is writing templates. And I'm going to kind of fly through this slide here. We have a config.toml, which is a configuration of Hugo. So right now we're only talking generation. We're not talking hosting. We're not talking anything outside of that. So config.toml is the Hugo configuration. Content is the content Markdown. So the content directory structure is where all of those Markdown files will go. That's where multiple languages will go. Data is where you host data files. So you can have blobs or structured data that you can then render into your HTML page. So we do this for releases, for example. We have data of YAML of the releases. They get generated and published onto a website. Layouts is the HTML and shortcode portion of the site. So as mentioned, one of the really awesome powerful things about Hugo is the fact you can templatize and break apart so many different chunks. And so when you're writing a webpage, all you need to do is understand Markdown and being able to contribute to that Markdown component of it. So it gets generated into HTML. And all the magic behind the scenes is layouts. The second, or I guess not second, but the next item here is the static, which is your files and images. This would be things like your JavaScript, CSS, you name it. More of the things that aren't going to change, much like images as well. Now the last piece there is themes. So themes is not a required piece of Hugo. You can write your own. You can use some from the community. But having a themes directory there and a config.toml that points to it tells Hugo, hey, when you build these websites, use these themes and do these certain activities. So having said all that about Hugo and about directory structures and what Hugo understands, looking at this now, it might make a little bit more sense than when I first showed it. You see we have archetypes, we have content, we have data, there's some other folders there I didn't talk about. But if I run Hugo inside of this website directory, it will build those pages and it will serve that HTML page at the end of the day. So I mentioned there's a config.toml. Here's a zoomed in picture of what it looks like if I were to click into and go more into the Hugo details. Here's where you can see I'm setting the theme doxy, which I'll talk about more in a second, and some various pieces here around URLs and titles. So if you're following what I'm talking about when it comes to Hugo, when it comes to generation, it sounds like we're living in this magical fairyland of the website just working. Unfortunately, the reality is, is data changes, Kubernetes changes, a lot of things change fast. So for example, if you look at this site here, we're talking about supported version skew. If we wanted to, we would have to change so many different areas in the file for each release if we didn't automate this in a way that was repeatable. So that's where Hugo short codes come into play. So here we are looking at markdown. This markdown is going to call a Hugo short code. You'll see in the parens or the brackets, a piece that says skew, latest version, that is a Hugo short code that is calling some of the superpowers inside of Hugo. And what I mean by that is there's certain things that are driving this data when it gets generated. And so it makes us change one place that reflects across multiple pages. We leverage the data in the config.toml. So once again, I like to kind of peel back the layers of the onion and talk about what it actually is. And you can see in the red circle here, it is in the layouts folder, which is our HTML. And it is our short codes called skew, which is the first letter you saw in the markdown. Now we don't have the time to go deeper into the Hugo code or the short codes here that we're looking at. But ultimately understand that this is a dynamic way to create a version on the main website. And I want you to take a look at the site.params.latis here. So that's really the key of all of the magic. The site.params.latis is actually calling the config.toml in Hugo. I mentioned the config.toml before, but here you can see at the very bottom there there's the latest version is v1.22. And so what that short code does is take it and changes it on the fly at build time. So every single release, every single change happens one time in the config file and then hundreds of times across the website. It's really the magic behind the scenes of what is keeping kubernetes.io running. I mentioned before we leverage a theme. There's Hugo's theme called Doxy. It is created by some of the tech writers at Google. And it is supposed to be the best way to present technical documentation in a very opinionated way. Once again, kind of demystifying what that theme is. It is actually a sub module that is inside of the kubernetes website folder. And it's a get sub module that is maintained out of band. So this means now I kind of talked about the importance of data and how we manage data. Now we're talking about the theme and how do we manage the theme. And so by taking it and putting it in as a sub module, we only have to update that theme sub module as opposed to doing multiple updates to a custom built theme for example. So a couple key points. Everything is code. It's all driven with code. Hugo generates HTML files from markdown sources and shortcuts are the secret sauce that build the various components and config.toml is Hugo's boss. Hugo knows where to look at to get the information as needed to run successfully. So this is all great, but however we need something to host it. Up until this point, we're talking about markdown and mashing it with Hugo to generate a static website. Now we need a host and kubernetes.io uses netlify. One thing I wanted to call out here is netlify has a very similar construct like Hugo does where it understands a configuration file. So this allows us to take away everything I just talked about and netlify says give me a git provider. Give me a repository. And then let me go to town and build the site. So you could actually deploy the kubernetes website with your fork on netlify almost one to one with what is running in production today. And I believe this is part of the netlify free tier and you can play with just like it would be in production. But now you have full control over the repo how it works. You can try to break it. You can do whatever you want. It is all available to you. And so this is configured via netlify.toml file in the root repo. And if we're looking here, you'll notice that there is a netlify.toml. It's not pictured here. It's the same root structure that would also have the config.toml. And the netlify.toml says some of the build variables that netlify should use when publishing the kubernetes website, some of the commands that it would use. And some of the key points here is that netlify is looking for the netlify.yaml in the actual kubernetes website repository. At the end of the day, netlify is going to call hugo-eshminify if you start to pick apart some of the underlying commands that are being called. Inside, so when netlify deploys a website, it does a build. I think it's containerized. I'm not entirely sure. It builds the website using the netlify.yaml, runs a hugo command. The hugo command runs in that directory realizing there's a config.toml. And then netlify has the ability to wait till the site is completely up and running prior to switching the traffic over. So that means that the website kubernetes.io is rebuilt hundreds and hundreds of times a day. This is awesome. This is really also part of the secret sauce where you can have so many authors creating PRs, merging PRs. And as long as the site is live, and some approver has said that this PR looks good to me, it means that as long as we can merge that in the site builds, it will get published automatically. So the whole get hugo-doxy combination plus netlify gives you superpowers. And it allows us to support multiple releases by using branches and different config.toml. So when a new release comes out and it's a whole different talk for another day, you could actually create a new branch and operate off of that branch, build netlify using that branch, and have those custom features, data points, you name it, all compartmentalized by that single branch itself. And so with that, I'm going to pass it over to Chris to talk a little bit more about getting involved. Thank you. Thanks, Jim. Last year, about this time, I was checking out some of the virtual talks from KubeCon while sitting on my exercise bike. And I realized that, wow, this documentation stuff is very, very cool. So here I am a year later as a member of the new contributor class, class of late 2020. And I wanted to share with you some of the things that I've learned over the last year. Again, I came about this from the world where I'd be sitting in these meetings and this happened for years where we'd bring in a new piece of software. And invariably, someone would ask, Hey, is there any documentation on this? And the answer, the answer 99% of the time was no. All right, so our job, and it's been a great job so far, our job as a community is to try and make the Kubernetes documentation the best that it can be. Okay, so contributing to Sid Docs, you can look at some of these bullets, they're pretty standard, but I'm going to look, I'm going to state these right off the bat. Number one, it's about learning. Number two, it's about knowledge. Number three, it's about working with really smart people, really cool people using advanced tools and automation. Number four, it's about sharing with the greater community. And even folks, maybe in your day job or your studies, share what you have learned. And most importantly, fun. I'm dead serious, I'm having a lot of fun working with these folks. There's a lot of great dialogue on the Slack message board. So like I say, it's, it's a lot of fun. Okay, many people ask, where do I go from here? The docs sort of go into it, but I thought I'd put together this little sort of graphic to explain that on the left, you just need to sign up. And it may be as simple as just signing up for the, you know, for the Slack message board joining that and participating either in the bi-weekly Slack stand-ups or the every other week Zoom call. So just come in, announce yourself. The community is extremely inviting. All and everybody are welcome. Start looking around, probing around at some of the documentation and how it's structured. Jim went through some of how things are organized in Hugo. So install that, play around with it. Get, you're gonna have to work with some of the Git commands. If you're flowing in Git, this will be no problem. If people are new to Git, that's perfectly okay. We can help you through that. I as one has had to learn some of the more advanced Git capabilities because in one of my earlier projects, I was the single docs maintainer. So I pretty much was able to do my own thing. But in this environment, we're collaborating with, like I say, a bunch of smart people and it's important to be able to understand how Git can operate. And finally, you need to open a PR. You can open a PR and cover just about any topic, whether it's improving content, generating new content, maybe fixing something up. Brad will talk about localization. Any and all contributions are welcome and don't think like I have to be a craft up sort of a technical spec on some advanced Kubernetes capability. It may be as simple as just reorganize in a paragraph so that it's much more accessible and understandable to the greater community. Okay. The CLI, you're required to sign this. It's relatively straightforward. You have a pointer right here. If you don't sign it and you push a commit, the system will yell at you and you'll have to go back and make sure you do sign that. So that's one of the initial sign up actions that you certainly want to take. Okay. Open into PR. There's a couple of slides on this. I won't go into a super amount of detail. The instruction details from the documentation are linked via that URL. But basically, you go into GitHub, you hit edit the page, you edit the page, you fill out a couple of fields in the panels below, you push it up and boom, a PR is opened. Others can start to review it. But no need to use get to bring down the repository and some of the more sophisticated methods that you'd use to open a PR. This is one of them. This is where you do have to bring the repository down, clone it, set your upstream so you can talk to your fork, if you will, as well as main. You create a branch, you make all the changes in your text editor. The most important aspect, or one of the ones that I found, is locally previewing your changes. So Hugo has an excellent way of doing that. You can do all of your review of the changes that you made, make sure it looks good, you know, the styling is correct, so on and so forth. Push your commit up into the repository and that will kick off the Netlify process in which you will have a preview. Okay, if you want to open your PR from a fork, again, won't go through these in details, but the instructions are there. I will say that the simple GitHub method is good for very short changes. Maybe you're correcting some sentence structure or grammar or adding some punctuation or updating a term. If you need to do some more sophisticated changes or the changes are a little bit longer than what might make sense using the GitHub process, then you'd want to open it up from your fork and work off a local copy of your fork. Okay, code review automation that's performed by a tool called Prow. This was sort of mysterious to me at the beginning because when I'd open up a PR, I'd see, you know, so these robot commands, you sign the CLI and then it would tell me a CLI rather than it would tell me a couple of other things. The one command that I've used is that when I do open a PR, I'll put slash assign and then my name. Now, if you want to kick it off to someone else, you would put their name, but that's an important one. The end game, the goal here is to get the slash LGTM and the slash approve from the technical leads and those folks that make sure that the PR is good to go. I've also used hold to say, I'm still working on this, it's not ready, please don't do anything with it. More on the Prow commands in that link. The automatic preview, now this is the second way of looking at the changes that you've made. As Jim pointed out, once you push the commit, the PR is open, Netlify will build a site for you, a preview build of the site, and you can go in there and look at it. And this is how other folks, other reviewers, other tech leads would look at that particular PR as well. And by PR, I just mean a change in content or structure of the documentation itself. So good place to look at the changes right there, see how they'll look at, see how they'll look out on the internet once they're deployed. Also a good place to add a PR description. This can be really helpful. Your people will like you more than they probably already do if you do add a better description of the PR and also any changes that, also any of the pages that are changed or modified via your PR. Okay, going to zip through here. Now this is before approval, right? You've pushed your PR up to the branch, GitHub notifies Netlify of this PR, it builds and then publishes a preview of the website. And it's also going to check to make sure that you have the CLA signed. So that's before approval. Once you've made all the correct changes and everybody says that looks good, you got the LGTM and slash approved, you're all good to go. That PR is merged and deployed out there at kas.io. Boom. Okay, the local preview. Again, this is very useful when you want to examine or review the changes that you're making. I've used the bottom one mostly, but you can also use a containerized image of Hugo to make these changes. But again, very useful use that to review any changes that you made. A couple of thoughts on, in terms of contributions, again, any and all contributions, whether they include a particular punctuation or a revised paragraph or something that you think needs to be corrected are welcome. Anything, no contribution is too small or too large to make this documentation better. Style, that's something that is important, particularly in the technical documentation environment. There's certain ways of defining code blocks or code snippets. There's a certain syntax. For example, we want to use active voice. So instead of saying A is sent by B, it's much easier to just say B sends A. So little things like that. So there's a pretty good, there's an excellent style guide within the documentation. Reference that to make sure that you can conform to some of those things. Oops. Again, typos, new content, any and all contributions are very useful, important and encouraged. If writing is relatively new to you, a good way to start is to just take it, maybe some bullet points and start to put together how you want to structure this particular deep piece of documentation. You could take those thoughts, put them out onto a GitHub issue where you would have the community maybe review and assist or help guide you towards what might be the best way of phrasing or structuring this documentation. Then you can go off and open a PR and add it into the documentation. There's also the point about don't try and be too verbose. Zach mentioned always be deleting. Obviously, that's something we didn't do with the 50 plus slides that we have to show you in about half an hour. Anyway, I used active voice, keep things short, keep them simple. No need to get into a lengthy article with a number of words that you need to look up in a dictionary. Keep it simple. Diagrams, I'm real big into diagrams. There's a dearth of diagrams within the documentation. They make any documentation more accessible. It's easier to comprehend and it's much clearer. Now, you don't have to do documentation for every single piece of, excuse me, diagrams for every single piece of documentation, but it is helpful. If you think that golly, it takes too much time or I don't want to get into PowerPoint in that nonsense. Mermaid by virtue of the doxy dev theme is a package that's included with the cube docs platform. The nice thing about mermaid is that it has a very simple, marked downish type syntax to create relatively simple diagrams. As you've got your documentation there, it's straightforward to just add a few lines of mermaid code inline into your text and it will generate a nice little diagram. Again, a diagram could be as simple as some boxes representing components connected by arrows that talks to another component or represents a flow. Very useful to those that are just not familiar or just learning about Kubernetes for the first time. The nice thing about mermaid as well is that it is an offline live editor where you can build these diagrams, see how they look, and then also each diagram generates a REST API. You could fling that around to your colleagues and ask them for, hey, this is what it's going to look like. What do you think? Then they can go in and work on the diagram as well. It's a great way of collaborating with diagrams rather than sending PowerPoint and various SVG files to those colleagues. Anyway, this is a lot of fun. You'd make a huge contribution not only to the open source community, but your colleagues, your colleagues at your day job or your studies, and it's really a good thing to be part of. With that, I think I'll hand it over to Brad. Thank you, Chris. Okay, I believe I am standing between all of you and the booth crawl with alcohol, so I assure you we are going to end on time. It's nice to have control. So I'm going to hear and talk quickly about wrangling PRs and localization and bring us home. One of the great things that we kind of innovated in SIG docs was the notion of a PR wrangler. The idea of having a PR wrangler is somebody who would do triage on the PRs coming in so that if somebody submitted a PR, it didn't just languish for weeks and weeks and weeks where nobody touched it or responded and people are like, well, what's going on? We took great pride in SIG docs at being able to have the very quick response time to at least initial response say, hey, your PR has somebody assigned to it. And if there were easy ones that the PR wrangler can actually go ahead and improve them. But otherwise they're traffic cop routing it to the right folks. And you can feel comfortable your PR is going to get handled in a timely fashion. So that's something that we have. And we always look for more volunteers. So it's a very great role as you're trying to get more into SIG docs, great to spend some time taking a weekly shift. We all take shifts like page or duty, but it's not so bad of doing our PR wrangler duties. Now we're going to talk about localization. Kubernetes is an amazing project and the growth across the world is huge. And one way that you can see the growth is there's active large numbers of localization teams volunteers that are actually translating the documentation into a large number of languages. Some of them are farther along than others. But thanks to Hugo and its support for localization, we are able to add this type of support. And we have a really vibrant community that does it. And you can see this is an example. The China team is one of our most advanced teams that does localization. And this is the What Is Kubernetes page. And I'm smart enough to look at the English and then do the translation. That's how I know it is the What Is Kubernetes page. And you can see that it helps to have it in the language. So these are the ones that we have now. We just recently added Hindi and Punjabi. So new teams coming on board. We have great documentation in the documentation on how to get started with creating your own localization. So you can see all the basics that you need to do to add your own localization. We also have a SIGDocs localization subgroup that I chair. And this is a group that meets once a month. We're doing a run on time. Five minutes. Not a problem, gentlemen. Not a problem. We will get there. So with the SIGDocs localization subgroup, we meet once a month and all the different localization teams talk to each other and they share best practices. So they share best practices and they also share tooling. So we have really great tools. The Chinese team pioneered some great tooling and the Korea team also have some great tooling about how to identify what needs to be changed, what needs the localization to be applied to. So we have great tools that are all described and we have the ability, great documentation on how to get started if you have your own localization that you want to get started. We have a Slack channel. We have our own Slack channel. We have our own mailing list. And like I said, we even meet once a month. It's a lot of fun. One thing to know about localization is a common mistake is people want to update something across multiple languages. So one PR makes this tiny little fix across five or six languages. Turns out that's a really bad idea. I know it seems like something you want to do, but it's much better that your PR should stay inside a single localization because otherwise it causes problems down the road for our folks and their branching. So just a safety tip there. We also support blogs and sig docs. It's kind of its own little omission, but you know, here's some great guidelines on doing a blog. Should not be a thunder pitch. That's not the place for these. Please don't put them there. Try and make the content future proof so it stays fresh. Should be original content. And so anybody can write these and submit these. So if you have a great idea for a blog, ideally original content, please go ahead. And so just to recap, so many great ways to come join us and contribute. It's a great place for new people to get started. There is not a friendly or crowd in the Kubernetes community than sig docs. And we wonderfully want to help you get started and getting contributing. So again, you can help with web design, report bugs, you can do some reviews, you can help with localization, you can write new content, and of course, new texts and diagrams. We've got some great tools based on Hugo and Netlify and get obviously to make things work. And if we took next steps, very quick. It's okay if you want to lurk, but we are always here to help. We're always here to help. And we're always here to help with our meetings to help let you know who's working on what and how you could help and how you can be involved. Again, some more information here. There's the sig docs slack and the sig docs localization slacks. We've got a Google group, Kubernetes sig docs. We have a meeting that's about twice a month that we have and it's the schedules are out there so you can take a look. Again, here's how you can get in touch with us. So if you want to take a picture of that, you can. And I've finished on time. Thank you all. Let's go have libations. Appreciate it.