Flock 2026 The Docs 2025 Community Initiative – Join In To Improve Fedora

over. Hello everyone. I hope you're all sufficiently caffeinated and awake. At least mostly. My name is Peter Bukowinski. This is Peter Boy. And we're here to talk to you about the Docs initiative that we started last last year. So, this originally started with a Flock talk a year ago. Well, where we were talking about flattening the roller coaster. By roller coaster we were referring to this uh phenomenon in Fedora documentation where uh once in a once every few years we would get a huge wave of of contributions and it would taper off and go down down down until uh the state of the documentation would reach such a horrible state that it would start pissing off a sufficient number of people and they would join again and fix it and then go away again. So, it went like this like this forever. So, we decided we were going to try to fix that and establish a long-term community of repeat contributors. Uh after that in in autumn 2025 we formalized it into a a formal initiative submitted to the Fedora Council which was accepted and started officially in at the start of November 2025 which also resulted in uh the two of us being temporarily on the Fedora Council which by the way nobody told me. So, imagine my surprise when I got an email from uh FAS saying you've been added to group Fedora Council. What? So, here we are. And uh >> That's Oh, okay. This is my part. Okay. A short recap what wanted what you want to to achieve. The most um the important thing is to or was to consolidate the uh docs infrastructure. Originally, we were scattered about Pagure, GitLab, GitHub, and two or three else. So, for a newcomer, it was it was chaos pure. So, nobody wanted to know where to do what. The additional problem was um at the same time, we wanted to consolidate infrastructure. We had to move from Pagure to Forge for Geo. So, and that started as a quick easy action. Uh we became better. It take its time. Took its time. Well, other thing is community work. That's a big failure or big mistake previously um endeavors to utilize docs were suffering from that they didn't do sufficient community building, community work. So, at the end, um we had a very active team, docs team, uh at 2022. Yes. Um but it was too small and failed to to to have to to have to make long-term work. Then we have a structure improvement need. Since we splitted Fedora into the editions and the spins and others, we have two two divided documentation. Many of the editions have their own documentation, and we have some kind of the rest of documentation, which is mostly quick docs, but there is an old administration administration guide, there is a specific specific AIM guide, and something like that. It's a chaos, as well. And we to improve that. Then we have urgently improve content. Um we have to have we have to establish a consistent structure of each document which is recognizable. For instance, we have to should start with the abstract in any time so we have a short two or three sentences what is going on. You want to have a um a link to upstream documentation in every of our docs and such and things like that. That is true for every documentation and specifically for quick docs which is a huge um a huge endeavor to get it up and running to get it updated because it's about a hundred articles. Some are dating back five six years ago and describe anything but not the current Fedora issue. And and we wanted to restructure quick docs from a content table to table of content based system to a category and tag based system because um most or many of the um or or many of the articles are relevant not only for one case or for one categories but for more than one so it's easier to use a category system instead of the more static um um table of content. And the other thing is we have um or well, in general Fedora docs does its name Fedora it has something to do with Fedora. But if you look at the standard or default Fedora procedures and um uh council and not and the teams and something like that. Fedora doesn't play any important role uh, in any term of Fedora. And one of these is we have a we have no consistent communication channel between developers, maintainers, and writers. Ending up, we have the writers wanted to change something, but they failed to get the relevant knowledge about technical details. So, one thing is we want to have build up um, a consistent channel between both. And um, well, and we have to this other thing, we have to incorporate docs docs topics in more um, stand- standard Fedora procedures. For instance, um, the special case is uh, the release notes, which are currently the docs is specifically dedicated the optional. You you must have various um, information in the change proposal, and but docs is not an um, um, a needed a thing. So, that's the problem that's the that's the around it's much to do. And we did already some things done. We talk about the scratch chart, but we have a lot of them left, and let's see. >> Yeah, so let's answer the question that I keep getting all throughout my life. What the hell have you done? Uh, so the most important thing that we did is that we appear to have actually established something resembling a community. Uh, so we have a formal membership process where somebody who joins starts to contribute can get vetted and approved by the other team members and officially join. You don't get a dark robe and sacrificial dagger yet. I'm still working on that. Uh And that's basically the most important part that we hope to accomplish, right? That's the flattening the roller coaster. And the key to that, what we've actually done, is that uh we've we're maintaining a high level of activity, which means that if somebody opens a an issue or PR, I or the other team members, we try to get back to that person as soon as possible. That doesn't mean we immediately fix the issue or immediately review and merge the PR, but even just dropping a comment saying that says like, "Hi, thanks for that. Uh you know, I I don't have time currently to work on this, but I'll keep it in mind and I'll check it out later." That's extremely helpful and it keeps people coming back. And some of those who don't come back eventually might want to actually join the team, which is awesome. Uh Are there some other things that we've done? Well, okay, there's the Forge migration, that's the obvious big step. We are pretty much finished with that. All of the content repositories that actually belong to the Docs project, that's the Docs Docs over there, uh are migrated and apart from those, we also publish some uh Docs repositories that we don't really maintain ourselves, but they belong to various SIGs, to the Council, FESCO, the Packaging Committee, that kind of stuff. All of these groups and SIGs maintain their own Docs, we just publish them. And most of those are also migrated, except for two that uh seem pretty abandoned and I'm going to have to fix that later. Some of some repos are still in GitLab, but that's a lesser issue than than remain than them remaining on Pagure. Uh Also, the new community that we now have has produced completely on its own without any top-down push from us, a beginner's guide, which is uh Basically, the idea is to provide some introductory docs for people who are who have never used not just Fedora, but any Linux before and they're here because they're just can't handle Windows anymore, which is seems to be more and more people. Uh long-term plan with that is to also produce If If any of you remember the Fedora handbook that used to exist about 2018-2019 and we used to hang hand it out in conferences. That project I It was awesome. It kind of went away because nobody was maintaining it, but we're hoping to use the beginner's guide to produce something similar and hand it out to people at conferences and events and kind of stuff. Uh Also, to enable more people to contribute to docs, not just in the docs project, but overall in six and so on, we are making we are completely revamping con- documentation contributor documentation. I I'm going to say the word documentation a lot today. Uh because that's that's like the entry point basic entry point for everybody who wants to join, right? So, that they don't have to figure out everything how everything works by themselves cuz there are some uh idiosyncrasies in Antora that uh Yeah, it's it's better if somebody just tells you what to do. As always. Uh as part of the Forge migration, we've also cleaned up a lot of our repositories. So, uh we're using a shared set of labels, for example. So, they're actually useful because previously uh there was a completely different set in pretty much any repo, and no as a result, nobody was using any of them because it was just a huge mess. Uh now that we have all of our repos in Forge under a a single organization, we can make use of the project boards, which we use for for example uh well, tracking long-term work, basically. What you would call epics in Agile. And for stuff like uh you know, scheduling topics for our meetings, which we have every 2 weeks. And yeah, one one big challenge that we have had with the initiative so far at least partially. Partially it was caused cuz I'm I'm lazy. Uh since we had to migrate our repos first, and since Forge basically half a year ago, it was missing a lot of functionality, like the project boards. I think they existed half a year ago, but they couldn't really do much. So, we couldn't use them for this project tracking. And so, our you know, we we've gotten pretty good at tracking immediate issues and at single topic issues, but uh for tracking long-term goals, which consist of multiple subtasks, let's say, that's been historically a problem, and we're going to have to really get on that after we get back from from FOSDEM. And >> Okay, that's the current status. And now what do we do in the next month? Well, we want we want to concentrate on three to four topics. The first one is an update of the docs portal page or landing page to include a section about contribution or contributors, which is now missing. We have two sections now, users guide and project and and Fedora project section where we're talking about the teams and the and the teams basically. And the user guide a user section which is user documentation. And we want to end add a third section about contributors information or something like that. Um it's quite a a planning I started about more than a year ago, but got stuck because um I will say Um though that's a an easy thing, but just in case someone of you is working in some contributors context who may be considering to come in contact with us to include you into these new sections. The big challenge is docs quick docs consolidation. There we have three three parts. We have to um get the content right. And we have to get well the from so the content from the technical side we have to update nearly everything of the 100 um articles. And we have to consolidate the generic recognizable context structure metadata and so on. And we have to switch from the um content table of content based sorting to categorization. Well, we are quite optimistic in the because we have already made an um an um an intensive review of every page and have a list where we as um uh as assess the kind of score about relative importance, impact, and currency. So, we can sort this list and sort out or make a plan. It isn't our ticket just in case um someone wants to check it. Um Well, this is a docs quick docs um side. On the other next to the third um topic is to to make a pilot um a pilot project of communication set up a communication channel between writers and maintainers or developers. Um that seems to be the most um difficult project. Um probably less work as a quick docs consolidation in amount of time, but um it's as for getting it done, it's there are a lot of barriers, let me say. You want to start with a um with a pilot project regarding the content and pick up one long-standing problematic topics, either kernel or Fedora and multimedia. And um I think we will start with one of those and try to get something up and running. So, if something someone of you is in store interested in multimedia and Fedora, please uh come up to us, so we can something can work something out. At least we got the the the team leader of multimedia to to join us, so it's a a big progress. That's quite some Or if you one of you is a kernel developer, you are invited um to contact us as well. That's the one one of the first as a pilot project here. And the other one is to be tackled the release note process. We want to include mandatory parts about user documentation for each change in each change proposal. And maybe in the long run to automate the generation of uh the release notes and to get a complete set of release notes. Not a well, some partial percentage of of of changes. And we have to make some other issue um trial to bring Fedora Docs better into the Fedora project as a whole. Something maybe you know, we have the our previous or prime our our best distributions are the editions. The edition have technical specification, something else, but they don't have to have a docs. So a user docs and probably there's another issue we should change. So that's a short overview. Um what we are going wanting to Please contact us on the Matrix channel. So we can make better communication about it. And now >> Right. So we're going just going to breeze through this really fast because we're running out of time. This is some stuff that we would like to have further in the future after the initiative ends. One thing that's important mostly is the content map, which uh uh you know, we're we're just a group of docs writers. We don't really have insight into what users of various types actually want to do. So, we can't document it. But you guys in various SIGs uh you're way closer to that, right? You you know what people uh what kind of issues people run into, like I don't know, I holy I installed now YouTube doesn't work. That kind of stuff, right? So, we would like to hopefully work with a whole bunch of people from across the Fedora project on creating something like a content map. And the set of I'm calling it minimum viable content. That's uh you know, a a set of criteria similar to how QA has a test matrix, where they have a list of things that must be tested for every release and they're making sure it works. So, you we would do something like that, but making sure that the the documentation for those things specifically is up to date. You know, and documenting known issues especially. Known issues are some of the most actually useful and commonly used pieces of documentation and that kind of stuff. So, how can you help? First of all, come talk to us on Matrix, please. We don't bite. There's actually even a fun conversation in there once in a while. Become a docs captain. Yeah, I kind [clears throat] of glossed over that. Uh it's a bit of a dumb term, but basically I would really love for every SIG and working group and so on to have something like a docs steward, right? I By that I don't mean somebody who actually writes all of the docs for that SIG. I mean somebody who thinks about them once in a while and brings the brings it up at meetings and tries to poke others to, you know, like I don't know, you're discussing some kind of an issue, some kind of a bug, and that person would think, "Hey, we should probably document that so there's info on the about it somewhere else than our mailing list and our matrix, right? Somewhere where people can find it." And yeah, uh document your processes, please. Uh 2 days ago we had this whole conversation about how contributors keep leaving, and uh what wasn't really said there was that every time somebody leaves the project and never comes back, there's some part of let's say tribal knowledge that leaves with them, and it never comes back. And then people have to rediscover this knowledge when something breaks, and that's, you know, less than ideal. So, ideally we would document everything in excruciating detail. Uh that's not documentation aimed at users, that's documentation aimed at the project. So, we're only helping ourselves when we do this. And again, please come talk to us, and we will help you get set up if you don't have any documentation currently, or if you do and it's uh barely maintained, we can figure out some way to help you. Right. Uh we have about 1 minute remaining, so if there's a question. >> Um this is from Justin over there. He said he would crash at some point, but I don't think he's reached um He asks, "What is the one thing both Peter and Petra are both proud of from the current span of the current Fedora Docs initiative? What is one thing that will likely span beyond the term of the initiative?" >> What's the What's the um beyond? Uh well, that should probably be the community building. I mean, we're you know, for all of this that's part of the initiative, it's not like we're going to just stop when it ends, right? The 12 months are going to run out and we're going to continue what we are doing. We're just not going to be invited onto council panels. But yeah, the community building is the most important part because without a functioning community none of none of the other stuff matters. Right? Because you you can make plans as much as you want, but when there's nobody there to actually execute them, well, they're just plans. >> Well, I want to um emphasize it's the first time since many years we had a quite successful process of community building. And we had double not double, but factor of four the number of people who contribute to Docs at the moment. So, it's a uh it's a it's it's hope for the future. >> Yeah, I mean I've been contributing to Docs for 13 years now and I've never seen the current level of activity like day-to-day, right? Not just on meetings, but people are actually talking in the channel and they're actually uh you know, merging PRs and talking to people who open issues and they're thinking of work for themselves, which has basically never happened in Fedora. So, that's also a thank you very much. >> [applause]