Flock 2025 Fedora Documentation: Where We Are, And Where We Want To Go

So I think we should start. somebody. Oh no. Okay, let's start our boy of the scientist at the University of Germany. My major is so and minor is mathematics. I have been using since release one of Ben took initiate initiative in 2022 I think to revitalize I said okay I joined the And as a scientist I'm used to work with text used to do creative works with volumes and so on. And I thought okay this can contribute the skills to Fedora. Um well we had a good start but short time after the fall down came again and we have not to care about doc techniques but I think we have to care about other events and that keeps my sociological part in and I hope I can contribute my sociological skills to overcome some issues with the team but we My name is Pet. I've been working on since about 2013. Uh I was originally hired as a techator foration. Uh basically I replaced a previous author who left the company who was working on the selection guide for six at the time and he was at the same time So when he was leaving this internal he has been doing since the beginning. So came out in 2003 and initially was very good. It was mostly by the fact that a lot of employees were basically working And for the first 10 releases for the first about 10 releases, it was pretty good. But then uh this original story started sort of catching up with because uh Redhead's publishing tool chain was insane and it was built for this huge enterprise library aimed at enterprise users and uh the contributors were paid to contribute. So uh there was sort of like a higher threshold for abuse they were willing to take. Uh So redhead was has been using the book as the language for the sources the documentation and publican was the the publishing software. The book is XML. So to write documentation you had to write raw XML. There were some snippets for various editors and that kind of stuff but uh not for all of them. A lot of people are using Vim which is a high barrier for to entry for you know new newcomers from like the community when somebody joins IRC back then and says yeah hey I'd like to contribute to Federox well the first thing that person would hear is yeah okay well install Vim learn how to quit it and it was learn it so that wasn't very good and then over time there was sort of attrition among the people in redhead like the actual employees who were doing the documentation. People started leaving the company for green pastures or they were just uh change roles people from dogs often go to Q for example. So uh yeah, contributions started going down and uh by 2013 when I joined uh there were basically three of us headtors and one community member who has been there for a long time there was Pete Travis or random music and uh he was just kind of ghosting I guess he was staying there because a long time So uh after a while I was pretty much the only person left on federal in 2018 I was I switched teams and uh I went from professionally working on red enterprise documentation to being actually paid to work on federal documentation. So uh I was holding that for let's say for a while and Then we had this revitalization effort which uh was yeah basically Benoton's idea. He did a ton of work. We also had the switch which fixed the like the tool chain to a heavy degree. Cassandra is very lightweight. You can build a preview locally and it takes a couple of seconds instead of several minutes with public and It doesn't do very strict validation. So if you if you make a tiny mistake, you don't have to spend a ton of time hunting it down. It's a lot less annoying. Yeah. And then contributions started to fall off again after the initial excitement sort of died down back down again. This is the story of federal it's a roller coaster which we see as a problem and we would like to get off that. So what are we looking now since about 2022 we have a redesign page and we have big which is the most uh like most commonly used part of the actual documentation that we have because it's Like if you don't know what it is, it's basically if you took the like most common questions on ask feder and turn them into sort of a I don't want to say wiki because it was originally actually on the wiki and we migrated it to our actual side but yeah it's it's functions a little bit bit like right and they're very short focused let's say micro articles was focused on a very specific thing like my drivers don't work. I have an Nvidia card. How do I fix this? Instead of let's say descriptive dogs where you get an entire essentially book, nobody wants to read the book for documentation. So nowadays uh we have some very strong contributions based around additions because before we had like one of the main issues was that a lot of the previous documentation was based around real documentation because it was the same people doing it, right? So, uh the most example was the system administrator's guide which was basically the system guide for 7 with the logos changed and with you know somebody just search and replaced rather than the price for Fedra which sucks because the target audience is just wildly different. Yeah. And most of our documentation was based around this model which was easy to do but less than ideal. So nowadays uh especially server and to some degree workstation are doing their own dogs straight for Fedora like writing from scratch server especially thanks to Mr. Boy. But we missing we're still missing a bunch of stuff and we're missing like an overarching strategy say uh we have a big gap in documentation for specific simple but common tasks that people ask about a lot. I quick dogs are basically this right but uh A lot of stuff that people ask about all the time on our forums or let's say stack overflow these kinds of sites are missing and we don't like we only know that a lot of them are missing but we don't know which ones is kind of like serving this purpose except the issue is that you have to have a fast account to actually ask a The average person doesn't want to register on a forum to solve their problem. They just want to Google it and find the answer. So that's a big issue. Yeah. So uh and like a lot of this is caused by our high attrition rate among contributors because we rarely get somebody like Peter or a few years ago that our contributor did a ton of work. But most people when they even when they join federal dogs and come to matrix and start talking to us and we work with them and point them to something to do help them maybe get familiar familiar with our tooling they don't tend to stay very long and we most of our contributions we get okay not most of our contributions But most of our contributors are what I call drive by contributors, right? They they show up, they shoot off a couple of PRs maybe, which is awesome. I love it. But they don't stay. That's a problem. And a lot of this is caused by by our tool chain. So for example, we have Federal Currently has 33 separate repositories and all over the place. Some of them are still on, some of them are in GitLab, some of them are in GitHub. And there is an easy way to find out like when you any page are three buttons in the top right corner, they will that will get you to the exact source file in the exact but nobody notices. I I don't know what to do about those like make them flash red or something. I don't know. It's it's like they're not there. And so only only the people who are already familiar with our stuff use them. And the other problem is that well this is mostly my fault and I'm a lazy bastard. So when somebody actually comes in and opens a PR, it can take me a while to get to the and review it. And that's demotivating to a high degree. You're finally like you made that first big step and you actually contributed something and it's just sitting there and it looks like nobody's nobody actually cares. So that person goes away and then there's a good chance we never see him again. I've been getting a lot better this recently, but it's been a problem for a while. Yeah. And the third problem is that uh we we kind of have the same problem that Fedraiki used to have, which is that there's a ton of existing content and almost no one actually knows what there is and a lot of it might be outdated. We just don't have the people to to go through the entire thing, throw out what's no longer So this is current state of things. If you follow the development of the last two decades, we have a similar cycle up and downs as we are knowing from the economics. Um so and it is a cycle which does happen avoid it always will always have some up and downs but the trick of the issue is we have measures to to influence the impact of influence amplitude the waves. So we will have to except that we have a certain amount of accounts over the long term. But we should take measures measures to keep the effect as limited as possible. But to be able to do that, we have to give up our until now purely technical perspective on doc. always look for technical solutions switching from one CMS system to another something like that part but we seldom or not at all to care about what are soft skills what is mon what is the communication structure what are the um decision making structures we have We have to we have to do well. The first sign of something is going down is the number of participants of the meetings goes down. The meetings itself um some meetings are canceled because no participants were there and so on. You have a continuous slowdown of communication and decision making structures. It's not only docs in Java and Fedora, but for you can see the same the same way how it goes with our Java technical. So the first matter is we have to take care of communication and we have to take care of group building community building tools and we have to ensure that you not just make a project but you have to make a project with se which fulfills some specific ina we are quite well equipped because we have Justin as a community architect or It's a community I take I think. Yes. So because that is a position there a resource you can use to take care of the communication part of of our work and to care about the communication and um well we can do this. Yes. Sorry, it's always a technique. Okay, I have to um Sorry. Well, what happens is we don't really have defined goals, right? We don't have anything that could be called a let's say minimum viable product. Uh every release we publish the release notes, but those are essentially just rewritten change pages. So the utility of that is questionable. And for example, the release notes don't even have a section about like if only if it appears in changes, we write about it. So uh if if I don't know, let's say Firefox gives a huge update and it now has VR or whatever. Uh if it's not a federal change, it's not in the although it would be relevant to to federal users. Well, but the trick is okay. Yes. Um, we have to actively influence those additional conditions which determine excess or not success of community efforts. And um and so we have to define our future projects not just taking into account a limited task perhaps. write article about something. But we our future project has to fulfill some criteria. I hope I um we have we need a project and we need a workflow which is able to create an engagement enabling attitude. You have to be outcome orientated in a broader sense not just write But it must be a bigger task. It must provide a focus for different skills. So we can engage several people with different skills. But the outcome of their combined work is one product and not several words. And it must be a way to to have a continuation. One step is fulfilled. These are a lot of additional criteria we have to to follow if you want to plan our future. And the sub project we have to take care about what to do when the downfall is setting in because sometimes there will be going down and we have to take measures to prepare for this. Um one idea is to to auto automate a lot of work tedious work. So that the effect fewer people engage in the process is not so visible as it is for now. >> Yeah. I mean with with a fairly low amount of new contributors that we get, we should really do a better job of like trying to keep them in the project as long as possible, which means making them happy, right? So there are some quality of life measures that I have in mind. Some of them have already been demonstrated to work previously like live PR preview. So if you open a PR builds the entire site with your changes and you can check that out like the way it looks like uh it's going to look like when it's merged. Uh rapid response to inquiries that's sort of something I already mentioned before. We have to let's say keep at it I guess we're trying and better contributor documentation we we do have some but uh again some of it's outdated it's very long unnecessarily so so nobody wants to read it that kind of stuff and help on hand and matrix we are actually pretty decent in that but there's always room improvement and badges. I'm actually currently working on uh revitalizing those badges which is uh it's going to be a tiny factor like nobody's going to write tons of documentation just just to get badges but uh definitely can't hurt. And also fun fact there have been dogs badges since 2015 and they they broke almost immediately and nobody fixed them until now. And the open for questions that question. Uh so my question is if you Choose one area of the Fedora Docs project that you could have an influx of help with, where would you direct people to turn their attention to most? >> Sure. If you can pick one area of the Fedora docks that you need most help with, where would you send people to go? Like if I'm if we have 20 people who are willing to work on docks, what would be your your priority to fix? >> [laughter] >> Please correct. I don't mind. >> It's not the issue is there's not we have no not a concept of documentation. We are the editors of documentation. The document current documentation is the owner of the Fedora editions. That's a big big progress he made because we don't have to rely on something. It is in their own interest that they writing. So the issue is what are they what are they like to write about and then we have to forward them to the specification. We have one area which is not specific is okay the addition agnostic part of that is quick at the moment and it is a former administration guide which is I don't want to read English it's building unfortunately our distribution guide always forwards people to that guide So if someone wants to write about addition issues like kernel or something like that then we are the persons who are entre questions. First question are there any documentation events plans like hackfest where generally someone from community could come and directly documentation and the MRS are directly merged and it's some kind of time limited activity that's first question second question you mentioned like it's easy to get lost in different kind of documentation spread all over the place are there any plans for having chatbot or something like that where genally you don't need But you just ask >> right uh so the first question we occasionally do workshop I mentioned the name earlier Frankly Hankley sorry and he has been doing those for a few years but it's it's not like a it's not on a schedule really right like he gets an opportunity invite from some let's say university something like that so he does work there I'm going I'm going to be doing a workshop in late June for some university in Kenya as well. They just kind of messaged me on my so I was like yeah okay why not but it's it's personally for me it's not something I do very often and I've never actually done it before so I wonder how it's going to work and the second questions second question about the uh we don't have any plans for that unfortunately that It took us five years to implement proper search on the site. Right? So I hope that answers your question. >> We have the main task of the doc team is not so to write as it was some time ago but to create to organize it to make it accessible or findable. That is the main task at the moment for us to have a plan. To have a plan what And um if you I don't know if it works. Let's have a look. Does it can we switch? Oh yes. This is the current user where we have a single page which can be the can where you are sure to find everything. This is the one we started with in 2022. But If you have a look, you see we have a lack of where and so I plan for a long time to add something to have a user part to have a contributor part and to have a community project part. Um but the site page is easy to make but the problem is to fill the boxes and to add agreement with the contributors to be on discussion just we have to start so to add our page to contributor on boarding process we are aiming it for 2018 something we are doing that but it's done >> thank >> [applause]