 All right, we're getting started. Hi, everyone. My name is Jared. Welcome to Valencia. It's really nice to be here. The last time I was at a KubeCon was in Copenhagen. So it's so good to see so many faces here. I'm here to talk about sharing knowledge, writing good docs for quick review. And for folks who are following along, I posted a Bitly link. It's public. It's Bitly slash KC-EU. Let me see if I can remember this. KC-EU-Docs, if you'd like to follow along, just for your own reference or for accessibility. But just to introduce myself and my passion for documentation, I'm a software engineer by training. But I've been a technical writer for almost 20 years now. And the majority of that has been at Google. My focus primarily has been on open source documentation with a pretty heavy emphasis on Kubernetes. So I helped lead the initial Kubernetes docs team. I was one of the first docs chairs as part of SIG docs in Kubernetes. And I helped lead that group for about five years up till about 2020. So I have a lot of knowledge about documentation. And I have just a deep passion for great docs that are accessible, that are easy to write. So a bit about the importance of documentation, if I can convey to you some of my passion about the subject and why it's so important to me, it's that the vast majority of developers want great documentation. They want it to be accessible. They want it to be inclusive. They want there to be clear processes and policies for documentation. And it's a key decision-making factor when people are choosing which open source or even closed source project they're going to go with. Most people, most developers prefer documentation to contacting supports or talking to an actual person. They want content that they can search, that they can understand on their own and approach at their own pace. And most developers see documentation and its incompleteness or its lack of existence to be a huge problem in the community. So I want to talk a little bit about a story that's pretty common to my experience when it comes to reviewing PRs from the community for Kubernetes and from various other open source projects that I've worked on. And this is a story that's about speed. It's about how quickly can you get a PR in for documentation? Because this is what most of us are focused on when it comes to writing. We've already written the code. We want to get the documentation in. We want it reviewed as quickly as possible and we want to be done with it. So I'm going to introduce you to two characters who are working on documentation together on an open source project. Our first character is Tony. Tony has just finished writing a feature for an open source project and he is about to crank out a docs PR. And our other person is Maria. And Maria is a docs reviewer who is here to, she's a senior developer on the project and she's reviewing both docs and code PRs for this project. So starting out, Tony's written this code. He has some docs that he wants to write up, send it out as a PR, and his goal is to do this as quickly as possible, like I said. So what does he do? What do most developers do? Well, we copy and paste, right? We find a good document that we like, we grab it, throw it, the mark down into a new file, pull out some of the content that exists there, write up some new ones, create a new PR, fire it off. Now, Tony might not be thinking much about what his audience needs at this moment because his focus is on speed. So he might write this PR as something that he focused on in the creation of his own code. And this is something that I think we all do. So Tony might write this PR of I created this new feature. This new feature had these difficult design decisions that I made. Here are some of the things that I decided when I wrote this and the code for it. And this is a really interesting technical challenge that this code solves. So he writes that up, creates a PR, sends it off. And Maria now, well, Tony and then waits. Tony waits and waits and waits and waits for a response from whoever's going to review this PR because he might not know who's going to review it. He might not have read any of the review processes. He might not know anybody in this project. So he sits and he waits. And Maria then takes a look at the PR and she might not know who Tony is. And so she starts reading the PR and she thinks, what am I supposed to do with this? Who is this person? What are they writing about? Maybe the documentation PR is separate from the code PR that Tony filed. So she doesn't know that this code already exists, what it relates to. There's no context. She doesn't know what she's supposed to be reviewing and why beyond the PR that she's received. So she suddenly has a ton of questions. And those questions she sends to Tony. And it's a barrage of questions. What is this? Why are you writing it? What's the specific focus? Why did you use this template for your documentation? And Tony takes a step back. He says, whoa, why do you have all these questions for me? I thought it was pretty clear from what I wrote based on my knowledge of the feature that I created. So churn happens here. And this churn can take weeks, sometimes months to solve where you have back and forth between the PR creator and the PR reviewer. What feature is like, wait, what are all the questions that you have about this PR? How can they all be answered? And my goal in this presentation is to give you some tips on how to stop this from happening. How to set context at the very beginning and how to prevent yourself from getting caught into weeks and weeks and weeks of PR churn where you as a PR submitter think that you were creating all the context for your reviewer and your reviewer is confused and sending you back tons and tons and tons of feedback that might not be appropriate or might not be useful for you. So when I started, I said this was a story about speed, but that was actually a lie. This is actually a story about collaboration and empathy and planning, which in turn leads to speed. So with a few tips and tricks in your back pocket that you go into writing a docs PR with or reviewing a docs PR with, you can make this process much faster. Change weeks of review into just a few hours. So let's start this story over again. Tony finishes writing his code for his feature. He wants to do the right thing. He wants to write a docs PR with associated content so that users can use what he's written. So he takes a step back and he looks for some documentation about how to submit this docs PR. Now hopefully your projects have some of this documentation, but if not, there's a link for Kubernetes process which you can borrow from, scale down to whatever you need. And if you need to scale it up to pass to what Kubernetes does, just grab me after this talk and we'll chat. I'd be really interested in what you're building. In this process, your project should have documented how to submit a docs PR, what flavor of markdown you're using. Are you applying any specific style guide? Are you using the CNCF style guide? Are you using somebody else's? Are there any templates that you're using? Any tooling? You can write maybe half a page, even less if it's just a small project or read me, just hey, docs go in the same repo as the code, here's where they go. But if you have a larger site that you're using, then having a document that lists some of your process be incredibly useful for people who are writing docs PRs. This is just a pet peeve of mine so I'm just gonna toss this out there. But Tony signs the CLA. So this is something that holds up a tremendous number of PRs. Both code and docs, I see it a lot more on the docs side where somebody comes in, they make a docs change, they don't sign the CLA and then suddenly we have to chase them down. Go find them on Twitter or Slack or wherever. It's hey, please sign the CLA so we can merge your PR. And sometimes it's really hard. Sometimes we don't find people. So PRs will just language without the CLA sign. So please, please, please sign the CLA. If you have a similar process for your project, make sure it's clear that people do that. Next step, create an issue. I like issues because they help track the documentation that we're creating, especially if it's a larger documentation set or a larger doc that you need to write. But the importance of the issue is that it creates context for your reviewer and for the public at large, why you're writing this documentation, who it's for. So when you write, when you create an issue, it's important to start with who your audience is. And this might seem daunting, but really you should spend maybe 15 minutes on this. Like, just take a step back, and this is what Tony's doing, is taking a step back saying, who is my audience? What do they already know? Maybe this is a new feature for something that a new user of the project is going to use. So it's like, okay, you might not have a lot of context for this project. So let me start with your developer, you're coming in the door, here's the project, here's my new feature. But understand what your audience already knows and what they're going to learn from your document. And just write that in your issue, maybe two sentences. In addition, if you're writing more than one document, you're gonna be writing an extensive set of documentation, make a plan, just make a checklist of here's some of the docs I'm going to create. I'm going to create a procedural guide for using this new feature, step by step, one, two, three, how to use it. And create a conceptual guide that's like, here's what this feature is, here's how it works. Here's some of the considerations you should have when using it. Maybe you split that up, maybe there's an additional reference. Regardless, it's useful to just list a few bullet points of what you're going to build in this issue. And last, it's a good place to CC your potential reviewers. So maybe that's somebody in zig docs like myself, or maybe it's a reviewer on the project. Give them a tap on the shoulder. Hey, there's some documentation coming your way. I'd like you to review it. This is just a way for you to sort of start that initial conversation. And then from your audience, you should be writing, you should be writing to your audience when you write your PR. Now there's a ton of books. I've written a book myself on documentation and how to write it well and how to focus your content. And I'm not gonna go into all of that here, but let me give you one golden rule for writing great documentation for your audience. And that is simply to write it in second person. And this sounds maybe too easy, but if you take a step back from what you're writing, like what Tony was writing with, we built this feature because we made these design decisions, that's not very useful for your users. What's better is this feature was created for you to do X, whatever it is. State it from their perspective, write it to them, write it to you. The other points in here are very useful as well. I'm just gonna gloss over those, but that writing in second person is the most useful thing you can do. Keeping it in present tense, don't focus on past decisions or future decisions that you're going to make. Like your user documentation is not a great place to put in your roadmap. So just like, don't talk about your next feature release in six months. Like, mm, keep it focused on what the user can do right now in this moment with what you've created. And of course, you can break out chunks, keep it readable, keep it skimmable and focus on like existing templates and style guides. So give a quick example. This is a very, very, very, very, very old paragraph from the nodes page in Kubernetes. And I'm not gonna read the whole thing, but just that first sentence. We built Kubernetes with the concept of nodes which run pods, which in turn hold containers. So this paragraph is trying to do a lot, but it's also written in a way that describes the person doing the coding not the person using Kubernetes. So just to call out a few specific things in this paragraph that you can apply to your writing. Look for places where you say we. Try to get rid of them. If you're introducing your concept like nodes, maybe you should call it out in some way. If you're starting to list, like this whole paragraph is trying to both introduce the concept of nodes and say everything inside of a node. Maybe that should be another paragraph or another page. Like look at places where you can simplify, but start with looking at places where you're not speaking directly to the user. So here's it rewritten. Kubernetes runs your workloads by placing containers into pods which run on nodes. Like, ah, doesn't that feel so much better? Like write it to your users. Start with you. And I encourage you to just use you in your writing all the time when you're writing developer documentation. It will improve your writing quality 100% overnight. So when you send your PR out for review, the most important thing you can do is to specify what kind of review you want. Tell your reviewer what you want from them. Set some context. In addition to the issue that you created that tracks your document, let your reviewer know, hey, maybe Tony knows this feature incredibly well. He wrote it himself. He doesn't need a technical review. But maybe he's uncertain about his documentation and would like a review for editing content and clarity and consistency. So it's important that he specifies that when he sends out the PR. Like, hey, I would like you to review this just for documentation clarity. In Kubernetes, we use tags to track this. So let's say you wrote a networking feature and you want somebody from networking to review it. You would tag it with SIG networking or SIG network. And somebody from that group, from that SIG group would jump in and review the documentation, make sure it's accurate from a networking perspective. It's what we call a technical review. Now, if you want a docs review and you just want somebody from the docs team or somebody who's knowledgeable about content to review, give you a peer edit, copy edit, what you've written, then you might tag it just SIG docs. All of our docs go through docs review. Not all of our docs PRs go through technical review. But most of them do. And we focus it on specific teams because we set the context of what kind of review we want from all of our PRs that come in. And from the reviewer's perspective, it's important that you have a rotation for reviewing. Let people know how often you're going to be reviewing your content. As docs PRs come in, are you doing it on a weekly basis? Are you doing it on a daily basis? Is there somebody on the hook for doing that? Creates a rotation to make sure that these PRs are reviewed on a regular cadence. Otherwise, things languish and then you wait till there's like 100 PRs in the PR queue and then you finally crank through them all and it's exhausting. You end up with a lot of duplicate issues that people are trying to address. It's best to just nail those out as quickly as possible and have it on a regular cadence. And when you give feedback, make sure it's actionable. Documentation is not as clear and consistent as what's good and what's not. So if you give feedback, say like, hey, this sentence is unclear, here's a way to improve it. Specify exactly what you want. And if you're unsure or it's just a nitpick, call that out as a nitpick. Hey, this sentence is a little clumsy. Just a nitpick, you might wanna consider fixing it. Doesn't have to be perfect. The goal is good docs, good enough docs. The goal is not perfect documentation. And it's important that good enough documentation gets published on a regular basis and updated rather than you hold something back and wait for all the perfect changes to be made to this PR before you allow it to be merged. We do, it's okay to write a reviewer guide. We have one for Kubernetes. I highly recommend people apply it to their own projects if they wanna borrow it, but it basically says, here's what we look for when we review a docs PR. And there's a link to it in this presentation. If you grab the presentation, please have a look. And then last, as feedback goes back and forth, it doesn't need to be confrontational. Like feedback should be a conversation. When your reviewer, if Tony sends out a PR and Maria reviews it, Maria might not have all the contacts that Tony has and might ask for things that Tony is like, you know, I could reward it that way, but that's not as accurate as what I originally wrote. And it's fine to say that. Just keep it conversational and keep it professional, keep it constructive. And of course, like once you're done, celebrate, merge your PR, there's any cleanup that you need to do, do it, close your issue, easy. Give yourself a pat on the back, you're done. Now, throughout this process, this might sound like a lot, but these steps shouldn't take you very long to do. So I just wanna emphasize that. Like taking half an hour before you write a docs PR to jot down an issue, make a plan, ping the reviewer, CC them on the issue, before you start writing, will save you weeks of time in the review cycle. And it will make for better documentation and a better review experience. So some items just to take away for doc writers out there. Let's do, you know, research the doc writing process first. Like take a look at what is available for you to write your docs PR before you start writing. Write things, create an issue to track your audience and what they need and any plans that you're making for your content. You have signed the CLA, of course, but understand like what your audience needs and write to them. Write in second person, use you when you're writing. Avoid we, avoid I, avoid talking about the design decisions that you made and speak directly to your user and what they need. And specify the specific kind of review that you want from your reviewers. Do you want a technical review? Do you want a content review? Do you want both? You might want both. It's totally fine to ask for. Might come from two different people. You might add two people to your review. Totally fine. But it's important that you be explicit about what you want from your reviewer so they know what to provide you. As a reviewer, you want to make sure that your process for making docs emissions is clear to people who are writing content for your project. Write a process for people to follow. Doesn't have to be long, but be explicit about what you expect. Templates that you use, any style guide that you use, any sort of conventions that you use, your flavor of markdown, can be literally half a page. But it will save people a tremendous amount of time and frustration when it comes to contributing content to your project. Give actionable feedback, have a rotation for reviews, and avoid perfection. Call out nitpicks, specify that they're nitpicks, but don't make it about perfect documentation. Make it about good documentation for your users. Here's some additional resources for folks. I know I mentioned a lot, like templates. If you don't, you have templates for your current project or you're debating on what templates to use. I highly recommend trying Doxy, which is a set of open source templates that are used by the Kubernetes team that are based in Hugo. There are many, many, many other sets of templates out there that you can use. Feel free to grab those as well. There's also the good docs project, which is an open source project with many, many, many doc templates that you could borrow as well as principles for how to apply them to your project. Feel free to take a look at those. If you're looking for a community to tap into, let's say you have documentation and you're looking to make the next step, and maybe hire somebody like me to work on documentation for you, or you have questions about, say, doc versioning or localization, translation, any work like that, that might be significantly advanced from your expertise. Then I would suggest reaching out to the Kubernetes community and say docs, which is the easiest way to get ahold of us is on Slack, or trying to write the docs, which is an open community of technical writers and documentarians like myself who focus on this. And last, I wrote a book along with several other people here in the open source community called Docs for Developers, a engineers field guide to technical writing which covers a lot of these processes in depth of how to write content, how to create a documentation culture within your project, and how to effectively review and measure the quality of documentation. So thank you. I wanna call out a few people. I wanna call out a few people. Zach Corlison and Jen Lamborn who originally proposed this talk, but due to unforeseen circumstances couldn't be here. So you have me in front of you. And I also wanna thank the SIG docs group within Kubernetes for all of their work, many of whom I've listed here. So thank you very much. And with that, do you folks have questions about documentation that I can perhaps help you with? And there's a microphone in the back, right in the middle there. But you're close, so you can just shout it out. So, I'm sorry, what's your name? Tim, so Tim asked a question like, what's my opinion of document-driven development? And I think document, I really like document-driven developments as a model and a concept. I do think documentation should exist along the spectrum of development. And for a lot of the work that I do within the closed source within Waymo, we start with internal documentation about design docs and how we are developing autonomous vehicle technology with content alongside code. And I see that model working really well. Your mileage may vary with it, but I really like that model. Big fan. Hi, this is Vojtek from Acuity. My question would be, thanks for the talk. My question would be maybe the context. You mentioned that you're a developer, you have a background, a technical background, but not every technical writer has this developer background. So my question would be, do you have any good processes or stories about actually the technical writers working with developers when it comes to some complex features and basically how do people who write documentation work closely with developers? Is it like you ask your colleague to show you the features and explain it to you in detail or is it rather that you have to build it yourself and then test and then get back to the developer if you have any questions? What's the process that works best? I think developers, yeah, you're right. I'm lucky in that I was a software developer before I became a technical writer and I still do a decent amount of coding, but that's not every technical writer. And I encourage people who do documentation, do technical writing to get knowledge of coding. It's important that you be able to understand your audience because you're writing to them. Now, they're not gonna have the expertise of the person writing the feature, which is totally fine. They should come in with the ability to embody the novice who's going to be using whatever it is, the product feature that you've created. So having some of that developer knowledge is really important. That said, we've developed processes within Kubernetes, for example, to make up for that. The idea of splitting out technical reviews from docs reviews is one way that we do that. We sort of separate the technical writer's work, which is going to focus on their understanding of the end user and existing content and how the documentation they're creating should fit into the larger body of docs that we have versus the technical knowledge needed to understand the code and say, this content is accurate enough to convey the right mental model for the content. So there's a way to balance that back and forth. And I think I do think I work very closely with engineers. I sit with engineers. I learn what they're building and I write from that perspective. And I encourage people who are doing documentation solely as profession to do the same. So thanks for the question. Hi, thanks a lot for the presentation, very useful. My question is just regarding, what advice can you give to those who the English is not the first language? So do you have any particular advice for them? Yeah, I think that when we have, we have a number of members of SIGDOT to speak English as a second language and they're phenomenal writers. I don't think it's something that people should see as a handicap. I actually think it like writing shorter, concise, simple language makes it easier to translate into other languages. And that's something that we focus on a lot in Kubernetes. So I think some advice that I would have is to, beyond the fact that don't get imposter syndrome and don't feel like it's holding you back, is to look at other doc sets that you like and look at other style guides that you like like Google style guide or Microsoft style guide and see how that applies to your writing and how you might improve your own writing over time. Also, I offer developmental feedback to people. So if people are writing documentation, they can send it to me and I will say, like here's how I would edit it based on, if I was in a hurry to publish it, but here is a bunch of suggestions I'm going to give you to improve your writing over time because I see some patterns in your writing that if you change, your writing will sound more natural. It'll be clearer, it'll be more concise. So you're always welcome to ask other writers for developmental editing. That's what we call that. And you're welcome to ask people if you're writing a PR for sick docs, you can ask us for that. Or if you know technical writers that you work with, I would ask them for a developmental editing review of a document you're writing and take that feedback to heart and see how you can apply it to other documentation that you're creating. Yeah. Hi. Thank you for the talk. And my question is, are you familiar with the documentation system called Divyu? And if not, what do you think about systems in general? Because what I realize in my everyday work is that people come to you documentation for different reasons. So I think that there should be some separation between or some different styles of documentation to cater to those needs specifically. How do you do that in your work? I don't, what was the system called again? Was it Divyu? Divyu, D-I-V-I-O. D-I-V-I-O. No, I haven't heard of it. I know that there's a number of documentation systems out there, especially around API documentation and reference documentation and CLI documentation. And those tools help auto-generate a lot of content for those tools, like reference documentation that's generated. And I think those tools are great. They help automate a lot of the technical underpinnings that people want to know and they allow you to be documentation complete without having to do a lot of human written content. I really like those systems. That said, I tend to prefer human written documentation for things that are going to be written, is going to be read more by new users, by people who are coming to the product and want to have a more human experience. So I prefer markdown for that. But I know that there's a number of tools out there and they're constantly changing. I know Stripe recently released, was it a flavor of markdown, mark doc that I've been playing with, that's really interesting. So there are more tools changing. I do see a pattern where projects will lack documentation and people will come in with the idea of tooling will fix the problem. And I would highly caution you against that. It's better to create content first and then introduce systems like you're mentioning that help automate or manage your documentation instead of relying on a system to do all the work for you. I have never seen this succeed. But thanks for the question. I hope that answers what you asked. I think I have maybe a good follow-up question. So I'm involved in a project that's been going on for like a decade and we've had pretty good documentation, I think. But I think the format is holding us back from doing a good job of keeping it up to date. So it's currently in RST and Sphinx and we're looking at porting that to markdown on MK docs. Do you have any advice on, should we just focus on moving to the different format first? Or while we're doing that, should we also review things and try to maybe keep an eye on things like second person and things like this? Ooh, I think a lot of it depends on the size of your docs at. About how big is it? Let's say in terms of pages, about 30 pages or something. I think with 30 pages you could review it. I would do a copy editing review and migration. It's likely from what you're describing, you're going to want to maybe chunk out some of that content into smaller docs. You might have 30 very long docs and you want to sort of chop it up. I wouldn't do that re-architecture at the same time that you're doing the migration. So I would migrate first, then do the re-architecture. But you can definitely do some of that copy editing that I'm describing here, because you're already doing a pass through the content. We might as well make sure it's up to date with 30 pages. If you were to say like 50 to 100 pages, I'd be like, I would do one thing at a time because the project's going to be so big. But at 30 pages, I think you could do it. And you just mentioned that you have to be careful with tooling and not rely on tooling too much. But you would think like switching to a new format like MK docs, which I feel is a lot better. I've written some new documentation in MK docs. I'm very happy with it. While I feel with RST is just not, it's not easy enough or maybe life preview while you're editing doesn't really work that well. Do you think that makes sense? That there's new stuff and it makes sense to make a big jump to a new format? I think it makes sense. And I think it's what's useful. I think the biggest signal that you should look at is what do your users want? So I would talk to some of your users and say is RST and Sphinx holding you back from contributing? And if the answer is yes, then I think you have a great signal. If the answer is no, it's like all of these other issues. It's complexity of the project. It's like I, you know, not a large enough user base, all sorts of other things. Then maybe you should step back and say, this isn't our, this isn't our number one priority to fix. But there are tools that can help you migrate as well. So that's a great instance of like using a tool to help you lift and shift that documentation over. Oh, we're time. We're time. Oh, I'm sorry. Well, I'll be hanging out here if you want to chat. Thank you so much.