Flock 2026 Documentation As Infrastructure: Why Fedora Docs Matter More Than We Think

Hi everyone. I'm Aditya Patil. I'm an associate software engineer working with Red Hat. And like I also work with the docs team. Like where I we develop and maintain the docs portal for Red Hat. So my topic for today is documentation as an infrastructure. So why does the Fedora documentation matter like more than we think? So first of all, the question would be why does the documentation even matter or what are the causes of the documentation to matter or not? So first let's suppose if the Fedora docs disappear tomorrow, what will happen? So the new contributors would struggle to get started with the Fedora setup. So if there is an uh new contributor who wants to come in, who wants to set up their workstation, and get started with Fedora, he would struggle with it. Then the users like would have problems if they have few of the problems that they can fix via the documentation, they would not be able to fix them. Then the maintainers would spend most of their time answering the questions what the contributors or the users have base for the smaller issues. Also the maintainers would have to give the solutions to the contributors or the users. And lastly, the knowledge would become based like concentrated to individuals rather than being at like disposal to everyone. So that would be the effects of Fedora docs like disappearing tomorrow. So let's suppose we have the Fedora ecosystem. And so usually developers what they do if they want to stress test something, they take out a piece of piece from the ecosystem which they and see what are the effects of what are the effects when it is like What are the effects of it on other systems? So that is how the developers do stress test. So if from this pipeline fedora ecosystem pipeline if we remove the documentation part so it would halt all of the ecosystem on its own. So uh fedora documentation not only it is like a journey for every user. So the for the users it would be like installing fedora getting started with the setup and everything like the workstation then learning about the new features which the fedora introduces. So those all would be from the documentation then the upgrades that fedora releases those upgrades also would be through the documentation itself. So that that for the users the power of documentations come comes from comes to use by this. Then contributors would like they would have hard time they have they use the documentation for getting started then like understanding the workflows of how the documentation would be or like how the workflows of how can the contributor contribute to the fedora project. Then packaging software then for maintainers documentation is a way to share knowledge and get out like have the releases known to all of the users. So documentation like plays a major role for the maintainers. Then it it also helps in scaling support like providing the support if we have some of the features which the maintainers have pushed recently. So how would they know that these like how would the users know that these uh uh like these features have been pushed? That is through documentation. So, the maintainers have a separate journey through the documentation. So, documentation we can consider documentation as a as a part core part of the ecosystem, like the Fedora ecosystem. It helps in the installations, the development workflows, then the release processes, also the packaging. So, any of the users that come or like the contributors that want to know how to like package the software or how can the contributor contribute, that also is comes through documentation. Then the user support, like I mentioned the common problems which the users face, those are solved by documentation. And also mentorship, so the uh ongoing like the dev ongoing development on Fedora projects. So, the maintainers, they mentor the new contributors through the Fedora documentation itself. So, it is like an interconnected So, it is like a interconnected bus system where Fedora documentation is the central part of every aspect of the Fedora ecosystem. So, let's suppose we have a architecture wherein the code base, like a pyramid architecture, wherein our code base is the topmost. But this topmost layer like this topmost layer is uh standing on few of the pillars. Like it is standing on the CICD pipelines, then it is package repositories, and build system. So, these are the pillars which support our code base, and they help the code base to like be deployed or uh let get the releases out. But all of this structure, whole of this is dependent on a single layer, which is the documentation infrastructure. So, this documentation infrastructure layer, what it does is it helps the users uh get get all of the details regarding the Fedora releases, then contributor onboarding, and also the project continuity. So, this layer constantly helps the users, contributors, and maintainers to get their day-to-day uh workflow uh going and also help them in new releases and new features. So, this is this is kind of a foundational structure, which we can imagine how the uh how important the Fedora documentation it is for the users. Yeah, so in and if there is any of the cracks in uh this uh like the base layer, then it would cause the whole of the pyramid to fall down. So, like that that much is the importance of documentation. Like that is what uh the documentation would stand for. Then uh there are practically like there are two views to see documentation. First is the traditional view, and second is the infrastructure view. So, in traditional view, what we consider we we like we consider that the docs is an optional thing that we can do after we have the releases done or after we have the code completed or the features done. So, in the traditional view, we uh don't have that much priority for the documentation, which is like uh which is not the case in the infrastructure view. But in the traditional view, the doc code has the most important or the code is most provides most of the value in the ecosystem. But when we think of the infrastructure view uh for the documentation, so the documentation itself creates the value in the uh infrastructure. Then uh in the in the infrastructure view for the documentation, we see that the documentation itself is a system dependency. So, we consider like we have the CI/CD pipelines or we have some of the services that we have deployed. So, those we consider like an uh initial initial part of or the core part of our application. But in the infrastructure view, docs get equal importance for the like in the infrastructure that we had built. Uh and in the infrastructure view, we also have like we have CI/CD pipelines for deployments and build systems. We also have uh pipelines or systems for documentation itself. For the documentation to be correct, for them to be tested correctly. So, everything that comes under the uh CI/CD and maintenance, that is also a part of the infrastructure view. So, what would be the cost of treating documentation as an afterthought and not considering it as a priority for our application or for development? So, like we um usually what we do, we invest heavily like we whenever we build an application or we have any of the systems that we develop, we invest heavily in building the CI/CD pipelines, building the code bases, then uh building the uh systems that will help us just to maintain the code and uh have us uh monitor the uh failures and everything. So, that is the part that we most heavily invest on, which is like a good uh like I would say it is a best thing, but documentation should also be uh we should also invest in documentation as an consider it equal to the code. Like we as we invest in the uh infrastructure, like the build system and everything, but we heavily under invest in documentation. What this causes is it causes the knowledge transferred to be limited to some of the users who have pushed the features or have the users get I don't like the users would not be able to get the release updates and features. So we should heavily invest in the documentation part also. And we like I mentioned that we should also have the onboarding pipelines for the documentation itself. But like this view which I just shared, so this view practically we have we have a broken built which gets an immediate fix, but a broken contributor guide sits for months. So why this happens is because whenever we have a failure in our code base or a in our day-to-day pipeline, the effects are much more visible. So we tend to fix them like ASAP or we have the support tickets or we have lot of things to support lot of things to get the pipelines or the code base fixed. But when a documentation link fails or there is the search is not indexed properly, the visible effects are not that great. So it is very easy for them to like it is very easy for us to neglect the documentation. So the real cost or the invisible friction if the documentation is not done correctly, it would be like there is a missing or outdated documentation or a broken link on the site. So what this causes there is a new contributor who wants to contribute to this like the who's a new contributor who who wants to understand and get started with contributing to Fedora. So he would have a hard time initially to like setting up the Fedora or getting to know the workflow. What he would do for like getting his answers, he would raise support questions. Those support questions would go to the maintainers and maintainers would uh like on the Slack or emails or everywheres maintainer would get the pings and they would have more of their time rather than doing the engineering part, they would have more of their time invested in solving the queries of new contributors and users. So, it would uh heavily cost us in engineering hours for the maintainers or the contributors if also if they are contributing as well. So, it would be like it would have a real financial impact as well. So, we have uh let's suppose we have a new contributor who comes to Fedora and who wants to contribute. So, what his initial uh thought would be that he needs to check the documentation to get started with the Fedora. He goes to the Fedora uh docs. He finds the documentation. He wants to like set up the uh This is like in kind of an example. So, he comes to Fedora documentation. He sees that I want to set up the Fedora. How should I set up the Fedora? Then but while uh exploring these things he sees that the search that he wants to make, those are outdated. It means those are not indexed and they are not properly mentioned on the Fedora documentation. So, this is where he loses some of his will to contribute or move he gets blocked off by moving further. So, even if he moves forward with that, there is a learning process or learning getting to know the workflows and uh so, he moves with that and while he is doing that, he if he finds some of the links to be broken those are redirecting to some other pages or those links are not even like they're displaying 404s or not even uh having any of the documentation on them. So, that would be a very frustrating thing for the contributor itself to have, and it was it would directly impact the contributor to uh also even leave the like uh change of mind to make the contributions. Like it is uh 100% possible that if I have uh I want to contribute, but there is no proper way for me to move ahead, it would be very hard. So, that this directly impacts in contributor retention. So, we have proper documentation, and a small fraction of the users or the contributors who come to the site or the Fedora site, they want the documentation to be correct. They want the more we uh is is easy it is for the contributors to contribute or them to get started, that the contributor didn't retention would directly increase. So, what are the improvements that we can make on the documentation part or uh invest in the documentation? First of all, uh writing the documentation is not uh the only part. It is just half of the job. The main part would be uh discoverability. So, a documentation which is not visible to a user user who is like who are a contributor who is like under pressure for a feature to get rolled out, and at that time he does not find the uh correct documentation, then that documentation might as well not exist. So, discoverability plays a major role in the uh documentation. So, uh the documentation should be properly indexed. It should have proper links. The navigation should be correct. The uh links should not uh respond with 404s. The matter should be uh well structured and easily uh like it would be in in a way that it would be easier for the contributors or the users to get started with. So, like I mentioned the uh documentation which is not discoverable, like it remains hidden and causes in knowledge transferability, like it causes issues in knowledge transferability, like I had mentioned earlier. Then uh Yeah, the uh documentation which is easy to follow, easy to find, and uh well-structured, those documentation are like those have the most site visits or those are practically the most uh used uh the documentation. So, that is what we should follow. And uh the disc after the discoverability part, so what is the infrastructure that I was talking about exist, like what are the layers of the infrastructure of the documentation that uh how it should be structured. So, first of all, the content should exist, means which means that the content or the documentation, it should be written and it should be well-maintained. Then the second part, uh as I mentioned the uh discoverability discoverability part, the content should be properly indexed, it should be properly searchable, and uh it should be present on the correct site or the uh correct it should redirect us if uh external links, it should redirect us to correct external links. Then third would be it should be actionable, which means that all of the snippets inside of the documentation or all of the uh like uh the snippets and the codes inside of the documentation, all of them should be tested correctly and they should be uh contributor-friendly. So, the contributor can directly come to the site, he can uh take the uh code snippet, he can add it to his code, or if there is a command that uh he needs to follow, he can directly copy the command and uh run it run it on it on his terminal, and it should work. So, all of these code snippets and all of the links should be uh well test tested and contributor-friendly. And lastly, the maintainers should like own the infrastructure as a whole for the documentation. So, not just the code, but also the uh documentation that we uh let that the uh maintainers have, or the maintainers should also contribute in uh for the infrastructure for the documentation. So, these are the layers which can make a great documentation and which can help in the uh like greatly in the Fed- Fedora ecosystem. So, uh what the these are some of the key takeaways from this session. First of all, documentation should be considered as an infrastructure, and it should be part of a uh part of our uh core uh engineering ecosystem. Second is, documentation that is should be considered as technical debt, which would be like if we follow this process, that would be like uh help the documentation grow very good and help the users get on-boarded very easily. Then, like like I mentioned, the discoverability matters as much as writing the content itself. Uh then, strong documentation would improve the contributor retention. Like I mentioned, the uh flow of uh how the uh contributor, if he wants to contribute, how the process would be. So, that would greatly help in contributor retention. And uh lastly, like the small documentation improvement uh would create outsized impact. So, they any of the uh processes that like I mentioned, so we follow any of the processes, we consider this documentation as uh infrastructure as a whole. So, that would uh smaller these small changes would really help for the Fedora ecosystem to grow uh like beyond what we currently have. So, that would be a very good thing to have. Yeah, thank you. >> [applause] >> Thank you very much for the talk. Does anyone have any questions? >> Yeah, thanks. Uh I have a question like if you go back to that slide where you have like the disconnect this one. Yeah. So, where do you think is the biggest disconnect? Because like yes, to me it is like actually overcoming the fear of like finding the documentation because like the documentation is decently easy to find, especially like you can just go to the Fedora website. You can maybe not so easily, but find the packaging guidelines. And then the packaging guidelines, I know people love to hate on them, but I think they're great. Uh like they they describe everything pretty well and I I mean, I read through them last year. I didn't find any broken links. So, like to me at least that part is very very well documented. Also, like the new package process for new contributors is also a very nice page that I feel like So, like where do you think or do you feel like the biggest disconnect is? >> Yeah, so uh currently what we have, like you mentioned, the documentation is very nice, it is very well written, and everything that we have like we uh, might not even have any bro, of the broken links and everything would be indexed properly. But, uh, moving forward or having the infrastructure to get the documentation, uh, as a whole, considering it as a whole as an infrastructure, that is what where the uh, the documentation like Fedora currently has the documentation very nicely. But, moving forward, if we follow these these, uh, systems like these what we say, like I mentioned that the, uh, search or the, uh, broken links, so this this all would be in whole. Moving forward, we should not have any of the broken links like we don't have now. So, that would be a very great thing to have. So, like that. >> Well, >> [clears throat] >> I agree with your analysis, but you're completely more or less. When I thought about Fedora documentation a year ago, I came near to the same conclusions. And we started to create a docs community initiative to fix a lot of issues, mainly exactly those you are explaining here. But, the that two interesting interesting things which of you all your items is the worst in your side of Fedora of the current Fedora documentation. EG, we have very few broken links because they are controlled in the in the CI process. But, where is the biggest lack of lack behind? And of course, I would invite you to join us. >> [laughter] >> We have a lot lot of need for people who who um support documentation in Fedora and to advocate for Fedora documentation in Fedora, which is one of the biggest legs I see in the Fedora documentation. >> Yeah, so the thing is if we uh Like my point is if we consider the Fed documentation itself as an infrastructure and then move forward So like we do not have any of the broken links which we like any of the broken links on on on the documentation side. But moving forward following this infrastructure it would be very beneficial. So we do not know that any of the link that is broken or that would be redirecting to any of the other pages. Like we on our side we have many of the links that there is no uh If there is an external link which is not available the site itself is not available. But that link is not broken but the site in which it is redirecting to that is broken. So those links if we are able to discover them and have them monitored correctly so that would be very great in helping the ecosystem. Currently the ecosystem is very nice and the documentation is also very well written because like as you mentioned the community project for the documentation. So moving forward if we have the documentation considered as an infrastructure itself that would be a very good thing to have. >> Uh so you mentioned it as an infrastructure uh how do we start because I'm like yes the the contributing guidelines or the packaging guidelines of themselves are very nice. There are also some parts of the docs that are very unfinished. Uh so and there there's just this like growing gap. So that for it to be become a part of infrastructure we would first have to catch up everything like finish all the dogs basically revamp a lot of them and that's a huge undertaking and how do you feel this could be achieved realistically? uh >> Yeah, like like you mentioned that few of the documentation first of all itself the content needs to be there. So I had the layers So the first of all the first step itself would be the content should exist. And after that we can consider about having the documentation to be an infrastructure but for that to happen the content itself first should be there. So we can first start by having the content ready for any of the specific feature or any of the specific documentation. Like the So the contributors uh >> I don't think that's really the problem at the moment. Uh we have a search engine which is introduced is it is it maintainable? Is it discoverable? It works. It is actionable. It is actionable. In each page there is a link where you can take action. And um well maintained they are more or less maintained as well. That is not really the issue. One issue is the question is it part of the infrastructure? At the moment Fedora Docs is not part of the infrastructure is not for the Fedora community or the developers community not relevant is nice to have but not a must to have. And that is one thing we have to change to make really um we bring things forward I think. That's one part one item in our um docs initiative but until now we are badly uh failed on this item at the moment. Um that's a that is my Well, well, that is my my side. >> Yes, like you mentioned that uh we need to consider it as an infrastructure. So, uh I would like to like give an example. We have our we like I work on the with the docs team for the uh Red Hat products. So, the docs.redhat.com. So, we have uh a huge number of visitors visiting our site because of the uh sheer amount of content and also because it is very discoverable. So, we follow a infrastructure like we have a proper infrastructure in place where uh we have the uh like I mentioned the uh links and everything and the documentation. And we have a structured way uh pipelines and everything for the documentation to be easily accessible to the users. And like you mentioned that uh we need to consider it as an infrastructure for it as well. Yeah. >> One last question. >> It's a it's a it's a comment. Just want to tell a little story. I uh did a post in the Fedora magazine about using a rag system to answer Fedora questions. And somebody pointed out, they said, "Hey, the answer is wrong." And then somebody came in and said, "You know what? The system works, but the docs were wrong." And so, I just wanted to point out that that I think now that we're going to get more AI stuff happening, it's going to read the docs. And so, the the the value proposition of good docs, I think it it goes up. It's going to matter more that the docs are right. Um also, maybe people don't read the docs because it takes a long time to read them, but the computers are going to be reading them. So, if people wondered, "Is it worth my effort to make the docs better?" I think now more than ever it may be. >> Yes, like correctly said because uh we have LLMs who get us the data or uh answer to any of our questions, but the source that they get the data from, that should be the most important part of the that should be correct for us to get the correct responses from the LLM itself. Like you mentioned. It would be a So, that is where the documentation or the content part comes in. That should be very correctly said. >> Thank you very much. We're at time. Let's thank our speaker again. >> Thank you. >> [applause]