 Hello everybody, thank you for joining me today at this very dire time of the afternoon and on a Thursday, but let's get started. So the year is 2012. What were you doing back then? Perhaps you were studying something, perhaps you had a different job, maybe you switched career over the past 12 years, many things have probably changed. At least for me, I would have never expected that I would be in this stage sharing some thoughts with you. 12 years ago I was in Guatemala studying and I'm very sure everybody had very different stories going on back then. But one thing that united us all across different countries and cultures and different stuff was something definitive. The Mayan apocalypse is about to happen, right? This was everywhere all over the news and some people thought it was serious and there were some kind of weird things happening, but at the end we are still here so I guess it didn't happen. But the other thing that was more defining of our modern world is that memes hit mainstream and that really changed how we live today and we still have it. Maybe the apocalypse is over, but the memes are still here, they have evolved so many times and I was a student in computer science so one of the things that I saw back in that era all the time was this one, the classic, read the funny manual. I was studying computer science but every time I had a question people would be like sending me variations of these all the time and I think they would be canceled today, but yes this happened to me, it was my daily bread when I had questions I was trying to learn, but back then we had manuals of 50 pages so we could watch TV and we were supposed to read the entire manual so we could use the remote control, but what if I had to learn something really special or difficult like my sequel? Well there's a manual for that, it's just that it's 5000 pages plus and I'm supposed to read it all I know it all right, otherwise I'm going to get sent a meme. Twelve years from now things have changed quite a lot, right? Now this is not how we approach learning, learning in 2024 is different and how does it look like, how do we learn something new and new technology and new project and a new library and that's what we have documentation for, we have changed the word manual for something more comprehensive and that's what this talk is about, towards great documentation. What does great documentation even mean? That's something that we'll discover throughout this talk, but first let's talk about documentation in general, like what is documentation even in the first place, the dogs right, dogs are documentation and that's pretty clear, but there's more to it, the project's website is also, oh no, I changed my slide by mistake. Let me introduce myself first, that's why I was just so excited about the topic that I even forgot who I am, but I am Jorge La Fiesta, I am the author of the Linux Foundation introduction to backstage course and now I'm not working much with backstage, but I'm instead looking in a cooler place called Rutley, we do incident management and yes, now I have to look at the screen. I also studied digital communication at UCLA and Alborg University in Copenhagen and most importantly, I am a certified sommelier, which means that I drink wine and I know how to do it, which is what matters, in my opinion. Great, so now let's get back to the topic for real about what is great documentation and let's get to see what documentation is and this is dogs, right, dogs are fine, but then there's also the component of the website, which is a very defining aspect of documentation that we don't often consider, because when you hear about a new project on a podcast or somebody mentioned it to you on QCon, you probably heard dozens of things that you didn't know existed over the conversation you have with friends or people that you know here and you Google and then you find the website, how many times have you Google a new project, a new presser thing and then you're like, ooh, I have no idea what this does, so why is it useful at all to me? That's because the website is also a part of the documentation, it's very an entry point on even is it worth my time to keep digging into actually even reaching the dog section, so that's why the website is an important piece of this puzzle of how we even learn about new things. Next, we have the Rhythmie, because for open source projects it's not only about the website, you can also discover a new project through GitHub, you probably seen trending repositories and stuff like that and that's also why it's an entry point to get here. We also have the contributing file which is a form of documentation because if a person's project doesn't get contributions, it's even open source or it's just like a sponsored company thing that is just open, kind of. So that's an essential part and we need to be enabling contributors. Another thing that is part of it is the issues on GitHub, they are also a way of documenting what's going on and we also have meta documentation about how we even orchestrating this whole thing, because you've seen yourself the projects evolve fast, they really go really fast, especially when they become popular, so unless you have a way of curating how this is going to evolve, it's going to go crazy and go wild. However, it seems to me that there is some incoming communication. Let's see, I think it's coming from outer space or some kind of AI-generated text. Oh, it's not playing. But this hall talk is inspired by a tech audit that happened, it was sponsored by the CNCF on the backstage documentation. Backstage is a very complex project, it has hundreds of pages on documentation and they took the work of going through all of the docs and figuring out what works and what doesn't work, what is confusing, which is a very commendable task. I have never done it myself but I just used their analysis. So in this talk, the methodology is basically going through the findings that they have and trying to get patterns that you could apply into your projects or the projects that contribute to, and that's the idea. If you're interested in the output of this analysis, it took them months to get it done, it's in this one meta issue in which they collected all the different recommendations for oh, you need to restructure this whole page or you need to add this guide or you need to change this part in the sidebar, it's very practical information and it could be interesting to see how a transformation of a big project documentation can look like. So let's look into the backstage of the backstage tech audits. We have seen that they analyze documentation in three components. First is the project documentation, which is the docs part, then they also analyze the contributors documentation on the website. So let's look at first the project documentation. What does it take to make good project documentation? First you need to understand who needs this documentation because there's different people who want to use your project, your library, and you need to be able to cater for them. And one of the clear ones is new users, right? This is the whole purpose of having a project, somebody else is using your project. So you need to make sure you have documentation that's ready and available and optimized for someone who doesn't have a lot of context and is interested in your project and that is a specific nature on the docs that you have to write. Another set of group is experienced users. You cannot give experienced users this intro guide. They have different use cases. They need to find specific information. Therefore your documentation has to be structured also to take into account this user persona. And depending on the nature of the project, you also have user roles, which is essential. It can make things very easy to read or very hard if you don't recognize the right user roles. I'll give you a very practical example. In the backstage documentation right now, I'm very familiar with it. So for me, it's just that I always mean I never understood it completely, but I knew how to move around it. And I didn't know how to make it easy to read. And the reason why it's complicated and the reason why it's hard to follow or understand even what's going on is because different user roles are convoluted into the same pages. So that makes it very hard because the audit even identified four concrete personas in the case of backstage. Because backstage, I don't know, is anyone familiar with backstage? Can you raise your hand? Okay. So for context, backstage is a very complex framework. So it can be usually installed by someone in an organization. So developers can use it. So those are the end users. However, the end users need documentation because backstage has a lot of features. So the person who just wants to check out the catalog, which is one of the features, doesn't need to know how to install backstage. They just need to know how to navigate the catalog. And then there's documentation for the admins, which are the ones who install backstage. They require a lot more documentation. But it's specific to their needs. And backstage is optimized for inner sourcing, which means that it can be extended by other teams in the organization. So that's why there's this other persona that requires a specific documentation for developing tooling on top of their instance. That's not going to be useful for anyone else except for this group. And then finally, there's documentation for people who want to contribute to the framework, which is also very common when people open source logins or features, because it's not that easy. It's not like it's a special way of developing backstage when you do this. So it's just about identified what are the different personas and then you can organize the docs. So we'll see an example of somebody who does this really well and it's open telemetry. I don't know how familiar you are with this, but it's very different to use open telemetry as a dev because you need to put the tooling in it or as an operator because you need to use it in a different way. And they provide this way of straight up just, are you a dev or are you doing the upside? This is how you're going to get started. This is super useful because then people can get started rapidly without having to weave through the things that are not relevant to them and then they can find value fast, which is what we all have to do now that if we don't have a lot of time to read things that are not relevant to us. That's one way of like dividing user roles. Then there's also the example of Hermitius. They have like a really nice documentation and you can see that they have this part for new user content. It's a specific type of documentation that's going to be useful. If you're new to Hermitius or you just heard about it, you want to know, for example, how does it compare with other options in the market and how like the fundamentals and like introduction to the introduction kind of topics. So you know what it is about because it's not an easy thing to understand. And then there's also another part for new users, which is about practical stuff. How do you get value as a new user? Because that's what we need to optimize for new users. We don't need to tell them a story of how they found there or we funded these three years ago because they don't care. They want to get to see if this is going to be useful for them and how much effort it requires. So you need to get them started and make them be able to prove value of your tool as soon as possible. So you give them like this minimal viral path that they can follow with practical stuff and some conceptual content and then they should be ready to go. So that's for different personas on the documentation. But then there's also different types of... I just don't trust this pointer. Okay. Then there's also project documentation types because not all documentation is the same. There's conceptual documentation. There's step-by-step documentation there's like business value documentation on how to showcase like this works. So there's feature documentations. So at the end, the whole purpose of documentation is to enable someone to do something useful with our project. So that's what we need to ask ourselves. What are we enabling people for? As I was saying, one of the first things that we need to optimize for is that we can have people prove value because nowadays your project is probably not the only that exists. There's alternatives. So you want to be able to explain to people why they should choose yours. There's also documentation that's useful for explaining the foundation parts because that's going to be very interesting so people can do more and learn how to make it more intuitive for themselves how to build on top of your project. There's also like the showcase in the features which is the midi part because at the end nobody is using the project for fun. They want to solve the real things. They want to achieve goals. So this is also very interesting to showcase like in a very straightforward manner. So they don't have to weed through things. Then there's hands-on development which is tutorials, guides, and step-by-step kind of stuff, maybe even little laboratories or workshops that you may have set up. That's kind of another type of condition that is required at the end. Let's look at more examples from ethios documentation. So you can see that they have this clear path where they have conceptual content which is literally called concepts which is just very clear and easy way of communicating that this is where you'll find this kind of content. But they also have key features just on the same level of hierarchy. The sidebar is very important in documentation because that's the first thing that you can see. You cannot expect users to like go through all your nav unopening all the things until they find the right path. So you can it's useful to have like this is what you can use. This is how you can use Prometheus for alerting. This is how you can use it for this, for that, for that. And that just simplifies everybody's life. And then there's also step-by-step content which is going to be drilling into the specifics of this is how you set it up for X or for Y. And it provides this like, you know, tutorial style kind of content which is always appreciated by people getting started on as a reference as you implement. Then they also have a little bit of a mixback in best practices, which is perfectly fine. And that's also what we have here as well, just some best practices for documentation in general. We have, for example, the concept this is something that the CNCF Tech Talks audit also recommended, having very short pages, make them very concise. We often have the temptation of saying, oh, well, I can put these docs in this page because it kind of talks about the same thing. But then you're going to make it very hard for people to find this information and very hard for you to keep it updated because then maybe a part of the documentation changes, but the rest doesn't. So it becomes very messy when you have versioning. It's not very clear what changed. So make the pages in solar. It's better to have 10 different small pages than to have one super long page for many recent events, for SEO, for discoverability of the content. So that's something that it's often the temptation to be like, just drop it in that page, but it's better to make it separate. Another thing is include an API reference, which I guess is very common, but just in case, mentioning that if you have an API specification, just drop it in the documentation. Make it searchable. That's going to save so many lives because we don't have time it's very easy to miss things in the nav bar or just very specific terms may get lost. So just make it searchable is invaluable for users. And this is also important. Make plans early for versioning because your project will definitely evolve. The API that you have today will not be the APIs that we'll have in a year from now or two years from now. You're eventually going to rewrite the entire thing over the course of years. So you need to be able to have versioning early. You may not need to do it like right the first year, but you need to be able to plan at least how you're going to support this. And that may include choosing the right documentation framework or knowing what you can expect in that regard. And then similarly to that is plan for localization because when your project because very successful, which you will because you're following the best documentation practices, you're going to have people that want documentation in other languages. And this is also a very nice way of getting contributions. It's quite common that people in localized communities want to contribute content in their own language, which is very nice. It's a nice experience and it's good to have it enabled earlier. So we have covered some some tips on project documentation. Let's briefly review some stuff for contributors in the commutation, which include things like the rhythm includes the contributing file and issues. So one thing to have into account is to have all channels of communication clearly marked because sometimes you know you operate on this court, but then do you know it? Is it clear to everybody? Is it really marked on the repo on the website? Because otherwise it's unclear where do we communicate or do we communicate some through some other Slack channel or it's better to just be very explicit about where you expect the communications and which what purpose. Are you going to say that you're going to have this court for support? And I don't know, like GitHub issues for all that kind of stuff or the GitHub forum. There are so many ways of engaging nowadays that it's best to make very explicitly available to the users how to communicate with you about the project and how to communicate that they want to contribute. How do you support them? That should all be documented somehow. It's also very important to have a scheduled meetings because the project is it's okay if you want to do everything I think that's maybe the case for a lot of projects, but eventually the project will grow so complex that you will need to sync up with your organization sponsoring the project or with contributors or with adopters to figure out how are they using it and get feedback from the community. It's often unavoidable to have regular meetings and I think it's very healthy because then the people can hang out and you can see a face if you have cameras and understand how people are using your project which is ultimately what's going to inform how the project will evolve. So that kind of meetings is best to have them scheduled on a predictable pace and that space has to be also very feasible and explicit to people so they can know when to join and how to join and which are the channels. So all these communication channels are just integrated and easy to follow. Then we have a guide for new contributors which is also going to be unavoidable there's always going to be that's what we want right well just as we want new users we want new contributors and that's that documentation can be the people that are going to be contributing they are like more more savvy let's say or more invested in the project so we do not need to make them as tidy as the new user documentation but still it's useful to give them like which environments you need to set up and all of these nice things so they can contribute smoothly and then another thing that is interesting for the contribution is the pod projects governance because if you are going to commit time to contribute something to this project you want to know what to expect who's going to own it how is support for your efforts going to be received or are you going to create this PR and it's going to be abandoned completely who do you reach out out if you have problems that's or who's even going to maintain this after this are you expected to maintain this feature forever like what's the commitment that's something that has to be communicated explicitly also for the well-being of the maintainers because otherwise the assumption is oh I'm going to contribute this and the maintainers are going to have to take care of it forever which is happening in many projects and it's very burdensome for for maintainers it's better to set very clear expectations now for the website some tips and ideas this is something I could talk about for I don't know hours because it's my job to the websites I I work in marketing but on the good marketing people so one recommendation specifically for open source project is to keep the website on a single source which is often the case that you have you you're building the docs in a repo then you have like the landing pages in some other place and it becomes very difficult to maintain so one recommendation that a CNCF does is try as much as possible to have a single source where you can compile it could be as its own special repo for the website where you can compile the the docs reference when you can compile the the API and the marketing landing pages because that's going to make it easy for you to maintain and it's going to make it possible for people to contribute which a lot of the times you want people to contribute to your landing pages and your docs and if you have one single place where they do it it's easy to tell them hey you just go there and change it if there's an error or if there's something that they want to a page or other tutorial something it's going to be easier if they have one single way of doing it another thing is usability make sure even though like a minority of people we use it on a mobile device it's still some people who might use it and generally it's going to make it easy for you to so the documentation is available for different kind of screen sizes thankfully we have already this day and age a lot of libraries for documentation that already do this work for us but just not everybody has a lot of those just a check and there's something very critical that is often left behind or not even rely on an open source project is having some sort of social proof because just as you need to learn how to use it and show value you can develop trust if you can showcase hey all these companies are already using us maybe you should try it yeah like we are trustworthy of your time and this is something trivial relatively once you have a few adopters just like talk with them and say hey do you want to be showcased in this page and you can work on cases studies which is going to be super useful especially for champions that want to use your project in their organization they need some resources to to prove to their boss that this is not some crazy open source project that there is something solid that people are using it and then they can trust better that's going to be a worthy investment another thing to consider and it sounds way too marketing but it's very real you need to take into account the search engine optimization for your open source project website and that may mean using the right terms making sure the mark down in your pages is hierarchical and compliant because otherwise what's going to happen is that like the private source competitors are going to eat your pages and they're going to create a lot of pages so you everybody searching for your project will not even get to your website because they they know how to play it and even if you're the source of reference they know how to like dump you down the the list so it's better to be prepared just make a good work with your the way you use the language and your your html and that that can go a long way and and protect you from being forgotten even in your own search terms and also keeping track of analytics is also useful to see for example you can detect how documentation is performing a little bit and directly by saying if the drop rate in this tutorial is like five seconds maybe people are getting stuck maybe this like command is wrong and people are just leaving because the amount of people who will tell you that it's wrong it means like a hundred people tried it and they just abandoned it until somebody tells you hey this doesn't work so it's better to keep some eye a little bit to see what's performing what's performing where are people dropping out maybe this means that they don't understand what we're doing or maybe we have to rephrase how we talk about our project in the homepage it can be super useful and then last but definitely noticed is planning maintenance of the website and in general the documentation is good it's healthy to go through the website let's say once a year and say oh this message in this is not really what we do anymore we find out that people are using us in this way so let's change our hero image or or or or tagline yes now what is great documentation that's the question that we wanted to ask and just maybe short some short pointers project documentation a great project documentation achieve something and that is that it helps user according to their needs and it enables them to find what they need fast so that encapsulates pretty much the the way of segregating documentation by different roles making insular smaller pages make it searchable we all we do that so the documentation can be useful to people according to the need we reach whatever they need and they we have optimized the page for that and then the contributed documentation enables people to contribute in a predictable manner that means that if I put my time maybe on the weekend to create a PR I know what to expect I know that the maintainers may be going to take three weeks to review it but I I'm okay with that but they because they told me so I do it consciously and then I know what's going to happen who has to approve it like I it's predictable and I'm comfortable when I contribute when to this project and finally the website the website's at least the way I see the website is that it should prove that your time is worth it's worth it to give a shot to our project because it can solve this real problem for you and it's yeah we can show you you just give us like five or minutes go to the docs but just getting the confidence like getting people to trust you enough to give you like five minutes is very hard in today's internet so that's that's kind of the purpose of the website and it's also useful for champions and finally all the documentation the great documentation has everything connected which means that the docs tell the same story as the website at the contributing content at the auxiliary channels at the meetings there's this cohesiveness and people know where to go when they need something that's really what we want to achieve and finally the message as well is contribute to documentation you don't always have to contribute code code is great but a lot of time there's a deficit in documentation contribution like this was from yesterday's talk on the state of backstage for 2024 and they mentioned this issue that I showed in the beginning and it's up for grabs there's many tasks very very good tasks for beginners that can get you involved in a way of contributing to a very successful project the backstage was the project with the most commits contributed in last year so it showed you that it's an interesting project to start contributing if you want to and documentation is a great way to start and yeah that's that's all I have thank you for coming there's this qr for feedback which I would really appreciate so I can make a very talk and if there's anyone that has any question we have some time all right I'm Nate a technical writer with the cncf thank you so much for going through this process and doing this well first off thank you for working with us on this program this was a lot of fun working with you and I'm gonna hijack a little bit here if there's anybody who is a maintainer in the room and you would like to to go through this process with us you're welcome to open up a service desk ticket or reach out to me on slack mate w and the other thing I'd like to let folks know about is every I guess it's the last Wednesday of every month we have a a tech writers open office hours for anybody who's got any questions about technical documentations we bring tech writers in we have conversations we go through all the stuff that Jorge has been talking about and the way you can find that is in the cncf I'll make sure that we put up a piece of information with the zoom details and all that in the cncf tech docs channel in in slack so sorry for hijacking thank you so much Jorge this is absolutely thank you thank you so much for saying that I think everybody should know it yeah great yeah Nate is amazing to work with so if you have a cncf project you should definitely go for it or just a commentation as he said for the open office it's gonna be amazing I learned a lot right thank you have it uh after a minute