 Hello everyone, my name is Celeste Horgan. I'm a senior technical writer at the CNCF And this is writing for developers. Take your project docs to the next level So let's start with a fun fact. About 50% of responses to the query how to choose a development framework on Stack Overflow mentioned documentation in the response Full disclosure, this is a pretty rough estimate done by me. I Spent some time googling how to choose a dev framework how to choose a dev ops tech stack, etc I'm combed through the responses by hand But the vast majority of them do mention speed of learning availability of documentation And how many responses something receives on Stack Overflow? So this is a bit of a call to arms for you This talk is really aimed at documentation maintainers as well as new contributors. So CNCF is a community of open-source projects and it's really really great that it's here But as far as an open-source project goes there is no dedicated support team There is no sales team and there are no dedicated technical writers unlike in a private company This is not to call out any of the partner organizations that we work with because what those partner organizations do stuff is amazing And we thank them for it It's more to say that the work that gets done is what the community chooses to contribute to And if we don't choose docs, the docs don't get done and there are consequences for that as we saw previously People look for projects that are well documented Especially in open-source because they don't have a company to fall back on so it's really important that those docs are well maintained So this is a talk not necessary about documentation maintenance though it's about how to become a really great documentation writer and I think we can borrow some ideas from English literature in our Journey to become a great writer. So this is the hero's journey. It represents an archetypal story In English literature, we think of the idea that most stories tend to follow a few different archetypes with a few different Variations the hero's journey is a really common one. Your hero is given a call to adventure They need a mentor. They go through some trials and tribulations and through those they gain the skills to return to their homeland And and vanquish and evil that they were maybe unable to conquer before their journey So they return triumphant but invariably changed by their experience And here's journey really applies to our user's journey as they go through the documentation Um So we'll be using this as a bit of a framing device to talk about how to write good docs from your user's perspective So let's start at the beginning the call to adventure Little Red Riding Hood is a great example of What your user is thinking as they approach your documentation so famous story Little Red Riding Hood is a very beautiful young woman. She's going to bring her grandma some food And she has to be able to walk through the forest to get there um, I Think this is I don't think this is a story that people are unfamiliar with When we think about this in terms of documentation then we can take away exactly one thing which is Your user always has a goal and your first task is to understand what that user goal is Um If your user were perfectly clever and smart and wonderful They would have no reason for coming to the documentation Invariably though they're here and now we need to understand why so that we understand what we need to write There's a few different ways that you can go about learning what your user's goals are the first is obviously talking to your users If you have community managers or dev rails or product managers or program managers These are great people to start identifying that user need But not every project has those So another way to go about this is to keep track of questions that have been asked repeatedly or keep track of Bugs that seem to come up time and time again in the slack channel What this usually indicates is a need that a lot of people are facing and if you write that down You're going to have pretty effective documentation for some subset of your users The final thing you can do is as you're planning your development story ask yourself what the documentation is going to look like One of the hardest parts about writing documentation is that as you develop something you become such an expert in the thing That you're creating that it's hard to zoom back out and think about what it would be like for a beginner So if you can bring that part forward that zooming out forward to before it you start your development You'll have a much a better picture of what somebody needs to know than you will at the end So this is what I want to talk and I really want to talk about new contributors as well though Which is you are invaluable to the development process for documentation for people here Because you have the beginner's eyes where as we just mentioned It's really easy to lose those as somebody who's working on a project So there's a number of different things that you can do that are really really helpful to project maintainers The first is to submit github issues and to open documentation PRs I've not met a project to date which is unhappy to receive a documentation PR Provided that the content is well-rounded and focused The next thing that you can do is to start talking to the project team and say hey Well, I was trying to execute on this use case or this scenario Would this be a good tutorial? Would this be a good blog post and maybe start working with them? And the third thing is to cherish your beginner's mindset I think that people are often a little bit afraid to approach open source maintainers with questions and to be perfectly clear The maintainers don't owe you an answer However You only get to be a beginner once and sometimes those questions are invaluable and super useful to those maintainers and creating good content so don't be afraid of Asking that question and don't assume that you're the only person who's having that problem because in most cases There's somebody else as well So let's talk about some common user goals for documentation In general These are ones that I've seen come up in my career over and over and over again So I think I'm pretty confident in saying that they're they're in play here for cloud native So some common user goals when somebody's looking at the docs Evaluating new text sacks to implement at their company. This is surprisingly common And a super underserved need in most documentation sets um Most companies don't have great feature lists For their projects and most open source projects don't have great feature lists either People look at your documentation to evaluate whether this is something they want to use or not Another thing that's really common is sort of learning just generally speaking like they're they've started to use your project at work and Now they need to be an expert in it overnight passing certification exams is another big one Supporting an existing system. We are super lucky here at the CNCF and that cloud native is becoming super ubiquitous And that means there are a lot of people looking at your documentation supporting your thing in production and finally somebody's developing a new feature for their own company and They were looking at your documentation to solve a specific problem that they are currently facing So the great thing is that documentation can meet all of these needs and more When we talk about evaluating text sacks concept docs are invaluable in that regards In regards to general learning to supporting existing system API references are super useful Once again on sort of passing certain exams tasks and tutorials and cookbooks are a huge reference for that particular audience and For the person who really just needs the answer to something specific Generally being well organized in your documentation or having good information architecture as well as making your docs really searchable Is super helpful to the person who wants to do that So we've been talking at a high level now, and so let's let's dive a little bit deeper Our hero has heard the call to adventure. They are in your docs. They want to find the solution to their problem Or the end means to their goal And now they enter this middle stage of the hero's journey. They're facing trials and failure So this is a Greek vase depicting Hercules slaying the Hydra Hercules is his story is famous for the many trials that he had to go through to regain his godliness But in each of those trials he had to acquire new skills and gain new Compensities in order to accomplish his goals and your user is exactly the same We need to give them the skills of documentation because as I mentioned For an open-source project. There is no support team for that. There is no sales team There is no marketing team. It has to come from the docs So luckily as a technical writer I Can tell you how to explain anything you ever want to ever And how to do it really really well all it takes are three simple parts First you have to explain the concept of something to people at a very high level. What is this thing? What does it do and why do I your user care? The next is a task. So, okay, I understand your thing now. Now, how do I use it? I have a goal. I want to accomplish my goal How do I use it and can you tell me about any pitfalls I might run into along the way? Finally I'm a user. I think I know how to accomplish my goal after all those tasks But Michael might be slightly different than the one that you mentioned the task So you need to give me some reference documentation show me all the things that your thing can do and then I'll decide Which of those functionalities I need to use to solve my problem And between these three styles of writing you can explain anything So let's dive into this in a bit more detail So concepts concept topics explain a feature at a high level. You can always tell a concept topic Because they tend to use a very standard sentence construction, which is blank isn't blank, which does blank It's almost always the first sentence in the concept topic and that's how you know you're there In general concept topics briefly describe or link to other topics related to the feature at hand And they describe why a user might care about a feature or what the common use cases for using something are Once again, I'm a user and I have a goal and I only care about that goal So tell me whether this thing you're describing it's gonna meet that goal or not So to give an example These are from the Vitesse documentation and they're describing a cell and you can see that sentence in the very first sentence A cell is a group of servers and network infrastructure and dot-dot-dot Which typically does dot-dot-dot um in the second and third paragraphs we start describing the linking to other concepts that somebody might need to know And further on it's a bit cut off in the screenshot. We start talking about what the common use cases might be The second component of really great documentation or tasks and in many ways, this is kind of the meat of the sandwich Test describe what a user can do with a feature You can always tell you're in a task topic when you start seeing things listed out step by step by step They'll often use numbers or bulleted lists Another sort of good flag for knowing you're in a task topic is you see a lot of code samples So anything that has like crud functionality create read update delete Will typically end up being in a task topic And you can also sort of tell you're in a task topic if the top the the title of the page has a verb in it or starts with the verb Because these are about doing There are lots of different style of task topics a numbered list is just one of them Tutorials are another type of task topic Cookbooks are a very very focused sort of task, which is this is the specific use case and the specific code You need to do it And similarly sort of example apps broadly speaking fall under the idea of a task because you are trying to help somebody accomplish something one thing to caution Particularly around kind of fully featured sample code like sample apps and cookbooks is As much as you think or want to feel That the code to speak for itself and it's standalone. I promise you it isn't I promise you it isn't and a Minimum you need to describe to people how they can take the code from github put it on their computer and make it work But in general at the very least commenting your way through a sample app is a really really great way to help your users out So batches of a test stocks for an example Insoles and quick starts are almost always task topics And once again the Vita stocks Do a really great job of showing that Kind of third paragraph and we've got a code sample and the rest of the page continues in this fashion So the very last type of topic that you need to describe anything Often seems like the least glamorous and often ends up being the most important particularly if you're you're in a pinch And this is reference so references provide lists of all options for a feature The one you might be most familiar with our API references which describe all endpoints and accepted data for a feature another one our java doc style Documentation descriptions of command line interface flags and what each one of them do Often these are honor generated from code though not always And the thing to keep in mind when creating reference topics is that completeness and accuracy is the most important thing to a good reference topic Which is why they're often out of dimmer into code People are surprisingly forgiving a task topic that maybe has one step, which is inaccurate But reference documentation is where you often go when something is not working the way it should And you need to sort of troubleshoot your way through it Which means if the reference is not accurate It's very very frustrating to your most frustrated users and you will hear about it. So a great example of how to manage a complex reference topics via auto generation was executed by our One of our Google season of docs interns last year. So shout out to Philippe for doing amazing work on this Because now the Kubernetes docs are auto generated directly into our hubos So We have our concepts which explain things at a high level. We have references which explain things in Quite a bit of detail and you have tasks which explain specific tasks something somebody wants to do Great documentation almost always has all three types You rarely see any of them alone. So to give an example of what that might look like Let's take another look at Prometheus's documentation and we're going to zoom in on this querying section so This first topic under querying basics, that's the concept topic. This is where they're describing What is querying? How does it work? Etc. Etc. Operators and functions are a mix of concepts and reference So they explain what an operator is and then what operators are available. So that's the reference part and Similarly, they explain what functions are and what functions are available Next they have examples which when you click into this specific page Is really a bunch of very short tasks and finally they have an HTTP API reference All three types of documentation Complement each other and they really shouldn't exist in isolation. So this is a great execution of that idea So let's let's head back to our hero's journey for a second We've got our users gone on an adventure and we've given them new skills And if we've done our jobs well now they can go back to the thing that they're working on and they can achieve their goal They can solve their problem So they're in this part of the hero's journey. They have had a change. They've received a gift and they are returning so Much like Jack here. So this is an image from Jack and Beanstalk, by the way Which if you don't remember the plot a lot a giant has been stealing things from Jack's family for quite some time So he is given some magical beans He he plants them and grows large beanstalk and then he takes his stuff back from the sleeping giant And he sneaks off And that's what your users doing at this point in the journey as well. They have what they need But it's not the whole story because again if you've read Jack and the Beanstalk any time recently the story doesn't end with Jack sneaking off Great documentation shows its users where to go next and It does this at a number of different scales So you can organize the entire doc set along a user flow, which is what is the beginning for your user? The middle and the end But it also does it at a much smaller scale, which is in an individual piece of writing. So within that document The beginning is usually the concept and then the middle is some task topics and then the end is a reference But what comes after the reference when you've imparted all the knowledge that you need Some well curated learn more links never go out of style asking for feedback is We found it marginally slowly Cooper 90s community, but I I wouldn't re-implement this on a new site But never assume that your user's journey is done just because they've reached the end of the page By way of wrapping things up and to bring this back kind of for the new contributors Documentation is a team sport new contributors and end users are kind of key to great documentation And to kind of bring it back to Hercules in this boss You'll notice on the left-hand side Hercules actually has a friend here So while Hercules out front fighting the hydra his friend is helping at the back And that's what you can do for project maintainers as a new contributor As I mentioned before it's really easy to get super deep into something and super technical and suddenly lose site of what it's like to be a new user So a great way to start contributing to open source and to start contributing to cloud native communities Is to start opening documentation tickets because they don't assume they'll know and Your contribution could be really valuable in that regards So thank you very much for your time everybody has been lovely to chat docs with you I will be around at the end of this presentation to ask some questions live um Here's where you can find me um if you want to get involved with CNCF project looking for docs help join us at the CNCF tech docs office hours If you're a maintainer look out for the emails telling you where these are going to be I and the other technical writers here at the CNCF hold monthly meetings where you can ask us any question about Documentation you want and we'll try and help you out as best as you can Um, if you are a new writer and you're looking to help out I encourage you to drop into a project's community meetings and See whether it's to see If you're looking for something a little more structured kubernetes sick docs is our biggest documentation community And they're the most well-equipped to help new Contributors and if you want to talk more at me I'm gonna be hanging around in the CNCF slack for another little while After this talk and you can find me on Twitter at sloth sorghum. Thank you so much for your time