Improving Fedora's documentation

At Flock, Fedora's annual developer conference, held in Prague from June 5 to June 8, two members of the Fedora documentation team, Petr Bokoč and Peter Boy, led a session on the state of Fedora documentation. The pair covered a brief history of the project's documentation since the days of Fedora Core 1, challenges the documentation team faces, as well as plans to improve Fedora's documentation by enticing more people to contribute.

I did not attend Flock in person, but watched the talk the day after it was given via the recording of the live stream from the event. The slides for the talk were published in PowerPoint format, but I have converted them to PDF for readers who prefer that format.

One piece of important information about the documentation team was not addressed until late in the talk—namely, the fact that the team's charter is to coordinate content and maintain tooling for Fedora documentation, with contributions from the larger community. Many people might assume that the team is responsible for writing all of the documentation, but that is not the case. The team is essentially there to help facilitate other people's work creating documentation, and to help with publishing of the documentation on docs.fedoraproject.org. This is not to imply that some team members don't do both—Boy also contributes to documentation for Fedora Server, for instance—but creation of documentation is not the team's mission. The Fedora wiki is also outside the team's scope.

Boy started the talk off by introducing himself as social scientist who works at the University of Bremen. He said that he has been using Fedora since its first release and he joined the documentation team in 2022, during an initiative led by Ben Cotton to revitalize the documentation effort. Bokoč, a Red Hat employee, said he had been working on Fedora documentation since about 2013.

The roller coaster

Bokoč said that Fedora documentation had a strong start "for about ten releases" because it was based on Red Hat's documentation. After that, it was downhill because "Red Hat's publishing toolchain was insane". Red Hat was using the DocBook XML-based markup language for its documentation and Publican to publish it. New contributors, he said, would join IRC to ask questions and be given little guidance on how to get started. For instance, a newcomer might be told "OK, well, install Vim" and be expected to adapt to writing documentation in XML with tools that are not suited for new users. That was, unsurprisingly, not hugely successful in attracting or retaining contributors.

The Red Hat employees who had contributed to documentation started leaving the company for greener pastures or switching roles inside the company. When Bokoč joined in 2013, there were only three people actively contributing to the documentation for quite a while. In 2018, Bokoč moved to working on Fedora documentation full-time, and in 2022 Cotton—who was Fedora's program manager at the time—led an effort to improve the documentation toolchain. The tools and processes are now much more lightweight, Bokoč said. Instead of DocBook, contributors can work with documentation in AsciiDoc using Antora to preview the documentation, which he described as faster and less annoying than working with Publican. Having dabbled with DocBook and Publican myself, I can certainly agree that they would not be my tools of choice in 2025.

After some initial excitement and interest, contributions once again tapered off, picked back up again, and tapered off once more. "This is the story of Fedora docs, right? It's a roller coaster, and we would like to get off the roller coaster." The slides for the presentation say that, currently, "docs are near dormant except for a few long-time contributors".

Things are not all bad, though. In 2022, the Fedora documentation site was redesigned and gained Fedora Quick Docs for "micro-articles focused on a specific thing, like 'my drivers don't work, I have an NVIDIA card, how do I fix this?'". The quick docs are now the primary area for contribution, he said.

In the past, much of Fedora's documentation was basically adapted from Red Hat Enterprise Linux. "You know, somebody just search and replaced RHEL for Fedora, which sucks because the target audience for Fedora is wildly different." Now, however, the teams producing Fedora editions are the main drivers of documentation. This is especially true of the IoT, Server and Workstation editions, whereas the Cloud edition's documentation "needs a lot of love" according to the slides.

Problems

What is missing, Bokoč said, is an overarching strategy. The project has a big gap in documentation for "specific, simple-but-common tasks that people ask about a lot". The quick docs cover some of that, but many things users look for are missing. The Fedora forum helps somewhat, but it requires users to create a Fedora account to log in just to ask a drive-by question. Most people, he said, don't want to do that. "They just want to google it and find an answer".

The problem is the high attrition rate, he said. Most people are "drive-by contributors" who don't stay long. They show up and make a few contributions, "which is awesome", but they don't stay. That is a problem. He attributed some of that to the scattered nature of Fedora's documentation repositories. Some are hosted on GitHub, some on GitLab, and some on Fedora's infrastructure. There is a way to find the source; each page of documentation has a button on the right-hand side of the page that leads to its repository. "But nobody notices those. I don't know what to do about those, like make them flash red or something?"

Another problem is that when someone does come in with a contribution, it may take a while for a member of the docs team to review it. "This is mostly my fault, and I'm a lazy bastard". That is, he admitted, demotivating for contributors. After doing the work to make a first contribution, a person's pull request just sits there "and it looks like nobody actually cares". Then they go away, and there is a good chance that they do not come back. He said that he had been getting better at reviewing pull requests more quickly, but that it had been a problem for a while.

Finally, there is a ton of existing content but almost no one actually knows all of what is available and what has become outdated. The team, he said, lacks the people to go through all of the existing documentation and throw out what is no longer valuable.

Solutions

Boy said the project needed to give up its "purely technical perspective" on solving contributor problems. "We have to take care of group-building and community-building tools". He noted that the team needed to be able to integrate the work of many people with different skills, over a longer period of time. Though he didn't say this as concisely, the obvious point was that Fedora cannot depend on single individuals willing to do heroic amounts of work to deliver complete documentation. It has to find ways to organize and assemble smaller contributions into coherent works.

He also noted that Fedora should provide more automation for tedious work, and Bokoč agreed that with few people stepping up as new contributors, "we should really do a better job on like trying to keep them in the project as long as possible, which means making them happy, right?" One example of that, he said, might be a live preview for pull requests so that people would see what their contribution would look like live on the site when it is merged.

Bokoč also said that (ironically) the documentation team's contributor documentation needed improvement. There is some, he said, but it was outdated and unnecessarily long, "so nobody wants to read it".

Another thing that would provide some motivation was to offer badges for contributions. Its impact would be limited because nobody would write tons of documentation just to get badges, he said, "but it definitely can't hurt". Bokoč added that there had been documentation badges available beginning in 2015, but "they broke almost immediately and nobody fixed them".

With that, the presenters turned the floor over to questions. One audience member wanted to know what areas the documentation team most wanted help with. "If we had 20 people willing to work on docs, what would be your priority to fix?" Boy reminded the audience that the documentation team were generally the editors, not owners, of the documentation. People should write about the areas that interest them. He did note that the team is responsible for some general-purpose documentation, such as the Fedora administration guide and kernel documentation, which are in need of help.

Another person asked if there were any plans to have a chatbot that Fedora users could simply ask questions to rather than searching the documentation. Bokoč said that there are no plans for that. "Unfortunately, it took five years to implement proper search on the site, so I hope that answers your question." The session wound down shortly after that.

Important but unloved

Fedora's documentation woes are hardly unique to the project. Documentation for most Linux distributions and open-source projects is lacking—and it is not difficult to see why. Even when developers are paid to work on open source, documentation is often left as an exercise for volunteers. Fedora's documentation problems are made even worse by the fact that it has a rapid development cycle with many people paid to develop software, and hardly anyone paid to help document that work. In that scenario, even when documentation is written, it often ages poorly as things evolve. Good documentation is like a garden; it has to be continually tended to in order to feed the community.

It is nice to see projects take interest in improving tooling and processes for documentation volunteers; one of the Fedora foundations is "friends", and it's not friendly to make people work with XML. But it would be even better if companies that benefit from open source (not just Red Hat) took a greater interest in funding the documentation that accompanies the software.

People who have the requisite knowledge to produce high-quality documentation are in short supply. People who have the skills and wish to deploy them in a volunteer role over the long haul are in even shorter supply. As long as documentation is treated as second-class to code, community building and tooling improvements will only go so far; projects like Fedora will probably have to keep riding the roller coaster.