Fedora documentation has been perceived as a weak point for years. But in reality, the situation is very mixed. I would like to briefly describe the current situation and how we got there. Based on this experience, I will present 5 theses about how Fedora Docs can be improved in the long term.
The current situation
The project is ‘dormant’ to say the best, showing all the signs of a deteriorated community and a ‘dead’ project.
- The team is dissolved with no consistent organization.
- Documentation has broken down into an active and maintained part, which is managed by the editions (mostly installation instructions), and a non-edition-specific part, which is largely obsolete with a few highlights maintained by groups with a special interest.
- There is a long list of unprocessed MRs, but no plan for improvement.
At the same time, the situation is better than it was about 4 years ago, when our documentation consisted of a completely outdated “Installation Guide” and an equally outdated “Administration Guide,” whose instructions were insufficient for installing any of our distribution media or performing any administrative tasks. We now have a strong documentation at least for some Editions, but huge shortcomings in Edition agnostic areas, specifically Administration topics.
This situation is quite unsatisfactory. And it has negative consequences for Fedora as a whole. Our distribution is considered “difficult” to use, at least in part due to missing or even misleading long outdated documentation. Other distributions are more attractive and are considered „easy“ and „quick“ to use. They are gaining users and thus also potential contributors, which Fedora is losing.
An example of this effect is ArchLinux, whose documentation is considered excellent and exemplary and – among others – a recommendation to choose it.
In the end, the documentation malaise contributes to the fact, that the outstanding engineering results achieved through the great personal commitment of many Fedora contributors do not receive the attention and impact they deserve.
A brief look back – a roller coaster ride
To investigate possible causes, it is helpful to briefly recall how this situation developed.
- At the beginning, i.e., during the first about 10 releases, we saw strong development in the area of Fedora documentation. At its peak, it consisted of a wide range of documentation on topics of varying scope. From a broad Administration Guide to specialized documentation on specific topics such as Grub or setting up a home server, everything was included.
- After the initial enthusiasm and appeal of something new, a period of decline began: A gradual decrease in the number of participants, meetings becoming increasingly rare over time due to a lack of participants, and eventually no longer taking place at all; loss of focus; loss of organization, goals, and planning. And with each new release, the amount of documentation decreased.
At the time, the technology, DocBook and Publican, was identified as the root cause of the problem. It was then replaced by another technology – Antorra and the Git workflow. - Once again, there was a brief resurgence of interest due to the appeal of something new. A large amount of the existing documentation was migrated, partly manually and partly automatically. Once the technical part was done, things started to slow down again, and in the end, only Petr remained as a “lone warrior” with a completely outdated installation guide and an equally outdated administration guide.
- The revitalization in 2022 initiated by Ben, initially brought a strong upswing, not so much in the number of active contributors but above all in the continuous work of an active core group on a defined and “focusable” task. There were different sub-areas that could be worked on by different contributors and produced a common result.
And a new problem was raised: a high hurdle for authors due to the Git workflow. This is familiar to “technicians”, but who write rarely documentation, and is a hurdle for authors and users who like to write but are hindered by unfamiliar tooling.
And just another change in technology was brought into play: the wiki. - Then, in 2023, it all came crashing down again, this time because two key members had to leave and we had no one to replace them. Another downturn began. Various initiatives involving online workshops were unable to stop this.
- Since mid-2024, the Docs Team has once again become a dormant entity. There is no focused planning or goals setting at all.
Instead, once again, a switch to a different technology came up: the documentation plugin of the discussion forum .
Afterall, we’re stuck in a slump again. Not quite as bad as around 2020, but you can feel it everywhere. At the moment, the current curation does not make the dire situation quite so blatantly obvious. However, with each new release, the shortcomings of generic, edition-independent documentation become increasingly apparent and urgent, particularly the Quick Docs and, above all, the Administrator’s Guide.
How to improve – the essential requirements
1. A change in technology is not a solution
Fedora has repeatedly discussed and implemented technical solutions or changes to resolve the Docs issues. However, the actual cause were not technical problems, but rather a gradual decline in the communities, recognizable by the typical symptoms mentioned above.
A technological change is more likely to destroy a community or accelerate a decline that is already taking place. It ends up uncovering new usage problems that don’t reduce the original problem but further hinder a solution.
Instead, it is beneficial to adapt the technology to the needs and existing skills in the community.
2. Extraordinary strong community building essentially required
The solution to Doc’s predicament is to build a strong community (or several communities) and put serious, extraordinary effort into it to make them viable and sustainable right from the start. In retrospect, this was the fatal flaw of Ben’s otherwise very successful 2022 initiative. We started with too few resources and focused too early on documentation work.
Any Docs community requires special efforts to be sustained. A community focused on a technical product has a quasi-natural long-term focus. In a Docs community, this focus is highly volatile. It requires members who continuously maintain communication, actively involve new members, recognize and seize opportunities to initiate communication within the team and with other teams, as well as continuously propose projects and goals that provide a focus for several different skills and members.
Such extensive and continuous community work is a prerequisite for effective documentation, alongside the actual documentation tasks. In the best case scenario, this happens automatically, with someone naturally stepping forward to take on this tasks. Otherwise, it is something that needs to be specifically considered and promoted when building a Docs team.
3. Self-contained short “Instructions” instead of monolithic “Guides”
Monolithic guides require considerable time and commitment. An author has to familiarise themselves not only with the chapter in question, but also with the documentary context. Follow-up work in subsequent or preceding sections may also be necessary to maintain over all consistency of content. This is an unavoidable consequence of the inherent structure and nature of extensive monolithic text bodies.
This peculiarity is problematic for a group of volunteer authors consisting mainly of regular users. Changes in membership are a regular occurrence in open source projects. Replacing or adding an author in a team writing and maintaining a monolithic text body is difficult and time-consuming, resulting in additional barriers. At the end it makes successful and productive work highly volatile.
However, it’s not just a matter of community, but also of usability and quality assurance. Shorter and thematically focused texts enable users to achieve success more quickly. The text may optionally provide links to broader information for those who want to acquire deeper knowledge. And updates due to changes in the software are easier and require less effort and quicker to accomplish and thus enable their timeliness.
4. Upstream first
The objective of Fedora documentation are the Fedora specific implementations and regulations, and how to accomplish a specific task, or use a specific software, in the Fedora runtime environment. This is an area where users and maintainers can excel. And this is where they are the experts.
Upstream projects usually provide general, distribution-agnostic documentation themselves. And there are numerous books and general information sites on specific software or Linux technologies. It makes no sense and is unnecessary effort to duplicate this documentation. The frequently referred to ArchLinux documentation is not a model to follow. Infact, it is in large parts a curation of various upstream documentations, compiled in one place and therefore the advantage of being easy to find..
The gap is applying this general info to your specific situation and Fedora distribution. And sometimes, finding this general info in an accurate, up-to-date, and readable version. A consistent quality feature of every Fedora documentation article is therefore its focus on the use case in Fedora and valuable links to upstream and more general documentation.
5. Bridging the gap between „engineering“ and „writing“
In Fedora, packaging and documentation are two completely different areas that do not interact or communicate in a systematic way. Although every “engineer” is quick to assure you that documentation is incredibly important, they are incredibly quick to disappear when it comes to contributing to it.
Vice versa, Fedora users are quick to post on our communication channels looking for solutions to problems or configuration suggestions for software. But they quickly disappear when it comes to making the solutions available to others.
At the end, writers get stuck because technical and/or valid usage informations are missing.
The documentation of the editions demonstrates an efficient alternative. Documentation is part of the scope of their Working Groups, thereby uniting technical and application/usage knowledge.
Of course, we cannot just apply this approach to all documentation. But it offers a promising strategy: Encourage and initiate communication between various experts – technicians, writers, users – but without introducing additional workload. The challenge is to create opportunities for such exchanges within the context of our existing Fedora Project activities. As an example, we could include an evaluation of the relevant documentation in the kernel test days. Or, we could dedicate one time slot on Flock to an exemplary technical area and its documentation. Implementing this strategy is without any doubt difficult and requires a high degree of innovative ideas, imagination and experimentation. And it will take some times.
Coda
The outlined strategy goes far beyond what can be achieved with a familiar SIG. A central coordinated initiative is needed to bring together several SIGs on a project-related basis. It also changes the tasks of the Docs team. Writing documentation is still part of the job, but a key focus is now on curating Fedora documentation and specifically initiating and instigating opportunities for exchange between different experts — in other words, community building.
I’m quite new to Fedora but I’ve been thinking about some of these issues recently, and it feels to me that you’ve captured many of the problems well here.
A few thoughts if I can add them. These are fallible because I know I’m extrapolating from what I can see, and I don’t have the whole inside track.
1. Documentation needs to be an integral part of Fedora, not an optional extra
Documenting Fedora seems to be perceived as a separate activity from the technical delivery of the product - and so we’ve had excessively loose coupling. The “Docs Team” is a satellite whose activity is not synchronised with product delivery and not considered mission-critical. If the Docs Team doesn’t have adequate resource, that’s thought of as kind of unfortunate, but not something that the project leadership as a whole needs to prioritise the remediation of.
A good first place to address this might be to look at the integration of documentation work into release planning: (This is what I was getting at in this post.)
Not every documentation activity is release-driven, but some of them are. (For example, “Getting Started” and other high-visibility pages should at least be reviewed for every release, but “Getting Started” wasn’t updated for either F41 or F42, and until very recently still listed the KDE Plasma edition as a “spin”.)
In principle, Change Requests do come with documentation tasks and these are tracked on the release schedule. But requirements may slip through the net here. For example, here’s a recent change proposal that claimed to have no documentation requirements, but in fact requires changes to be made in QuickDocs (not trying to single this one out, just that it’s recent and fresh in my mind).
Can we ensure that the release schedule tracks all relevant documentation activities for a release? Then if these tasks are behind schedule, they’re not just a “Docs team problem
” (shoulder shrug by the project), but they’re a “release in jeopardy problem 
” (high visibility at the program level)?
2. Lifecycle and sustainability management
To pick up a point from this, outdated documentation is often worse than missing documentation.
If a user can’t find what they need in the documentation, they can often find out by asking (here, on Matrix, on Reddit etc).
If a user finds documentation but it’s outdated, they’ll waste time doing the wrong thing, then come and ask for help, bringing with them a side order of annoyance. (And they’re right to be annoyed, when the distribution they trusted gave them misinformation.)
An important part of the strategy should be to ask: how do we ensure that once a piece of documentation is written, we have robust processes that ensure it gets updated when it needs to (or reviewed and affirmed to be still valid, when it doesn’t need updating?)
To be clear, I don’t think this is trivial at all – how do we know something is due for review? is it just a time trigger or can we do more with metadata to link a system change to the relevant documentation – but we should ask how we can do it better.
Hot take: if documents slip through this net and can’t be updated or reviewed, they should just be deleted. Outdated documentation is worse than no documentation.
3. Roles, responsibilities, recruitment and Red Hat
It’s right to talk about “bridging the gap between engineers and writers”.
A bit more radically: should the Docs Team actually be writers? Or should they be architects (of the documentation structure, tooling and processes) and editors (of content that engineers and users draft)? Can we create an expectation that subject matter experts don’t need to be great polished writers, but they need to at least provide the material that the Docs team edits, curates and publishes? This is again the idea of “documentation as an integral part of Fedora, not an optional extra”.
I understand where you’re coming from here, but there’s another side to this coin. There have been missed opportunities to bring in volunteer involvement to Docs.
Look around this Discourse forum, and there are several of us who devote plenty of our time to sharing our knowledge here. But (just my personal experience, and just from the last few months) there isn’t any “recruitment” activity that encourages us to turn that into contributions to the formal Fedora docs.
Also, you mention the long list of unprocessed merge requests. Each unprocessed MR doesn’t just represent a delayed update to a document, it’s someone who made an effort to contribute to Fedora, but had their contribution ignored.
It would be good for the Docs Team to publish a clear “Help Wanted” explaining how people can contribute, and to engage with those who do contribute. Engaging positively with first-time contributors (whether they do so by making MRs, or in some other way) should be a particular priority.
I do think that reliance on pure volunteer resources is an issue though. Can we look at how to make use of the relationship with Red Hat here?
It strikes me that (1) RHEL is a pretty well documented product, (2) Red Hat sponsors Fedora not out of pure altruism, but because what happens in Fedora can be ultimately used in RHEL.
What if Red Hat employees got more involved in documenting Fedora? This would really be shifting effort in time, rather than purely adding work. (After all, if a feature isn’t adequately documented in Fedora, then Red Hat has to do the documentation work at the point where it makes it into RHEL.)
Again on the theme of “documentation as an integral part of Fedora, not an optional extra” – has the Docs team asked the Fedora project loudly enough for what is needed to successfully deliver documentation?
4. Dealing with ensloppification
This isn’t really related to the historical issues discussed here, but something that deserves thinking about in the Docs strategy.
Can we do anything to deal with the degradation of search engine results and how it impacts users’ ability to get to the documents that we want to direct them to?
5 years ago we could probably have assumed that if a user described their Fedora query reasonably well and Googled it, they would get to a relevant bit of Fedora documentation if it existed.
Today, well… we all know how the situation has gotten. Deliberately broad and vague question – is there anything we can do to make that better?
Thank you for writing this and being prepared to reflect on the situation and propose improvements! I really enjoy using Fedora and I’d love to see us get to a better place with documentation.
If people only read one part of this post, I hope it’s this. We in tech love to chase the newest technology, but the problem is almost always people in one shape or another.
I think you’re right here, but it’s a bit of a “chicken and egg problem.” It’s hard to build a community around the idea of doing work eventually, but it’s also hard to get work done without the community. You need both. Your point #3 is a good approach to this, in my opinion.
Thanks for taking the time to write up this thoughtful analysis. I think it captures the history very well and gives solid principles for the next attempt to revitalize documentation.
There is a lot of documentation locked behind the Red Hat paywall. Any way to access or utilise it?
If access cannot be granted to everyone, can it be granted to Fedora Docs writers?
I think you’ve done an excellent job with your extrapolation.
The problem starts with the fact that documentation is not part of the “change completed” process. Only once this has been determined, a change gets actually incorporated into the beta. The same problem applies to entries in the release notes. Instead, a “blank entry” is created for each change and then regularly called up so that someone would please write a text. I discussed this with FESCo some time ago. There wasn’t exactly enthusiasm there, but ultimately it failed because the Docs team collapsed again.
These are two examples that are part of my detailed revitalization plan, which I am currently drafting.
Regarding outdated documentation. For the Docs Team, it starts with reliably determining whether a text is outdated. Age alone is not a sufficient criterion.
And regarding Red Hat, they also provide personnel support for Fedora documentation. But that can only be really effective if we, as the Fedora community, successfully manage to put together a functioning docs team.
Lets keep this on the agenda.
We would need to scope what exactly would be release blocking.
Could you please provide links or another source of information to prove this claim?
I’m pretty sure a free personal “Red Hat Developer” account is all that’s required to access Red Hat Documentation, but I have no idea about copyright or other licensing issues that may arise with using it.
Although it’s good quality, there are likely to be discrepancies with some aspects since it generally targets older RPMs with RH backports as opposed to the latest up-to-date Fedora versions. That would involve additional testing for accuracy, though for many things it would be a great foundation to build on if permitted.
You know what Hristo? Your question prompted me to find the free high quality Red Hat docs such as Red Hat Enterprise Linux | 9 | Red Hat Documentation
I might come across as critical of Red Hat sometimes, but its only because its the only enterprise distro I engage with. I wouldn’t use any other paid Linux
Maybe there is a way we can share some content with, or discuss with Red Hat documentation writers?
Does anybody know who at RH is in charge of or works with docs?
Here is the latest version:
As far as I know, all Red Hat resources that provide documentation or other types of information about their products are free and comprehensive. If you find an inaccuracy or even something that is difficult for you to understand, you can report it and it will be corrected. I’ve done it many times.
I know there was a Red Hatter who helped with the bootc documentation and even posted about it here on the forum. But I digress. As I understand it, editions and image based Fedora variants aren’t the main topic here.
From what I observed, RHEL documentation can serve as a complementary source for system-critical administration tasks, but for a general user-facing distro, it’s far too focused and does not serve as a great reference.
As ArchWiki has been mentioned, I would like to draw some sight on how they organize the information. Of course, it may have something to do with their user culture (less stringent on the free software philosophy, more focused on bridging Linux with the most current tech trend and delivering a wide selection for all kinds of user needs through means of AUR and such), but the model they operate reflects that,
An attractive distro documentation hub shouldn’t be just a manual for the OS product, it should aggregrate all possible best practices, quirks and fixes specific to the distro across a wide range of user experience (desktop, produtivity, multimedia, gaming, administration and such), to allow a first class referencing target when the user wish to build anything that change their experience, on the distro of their choice, expecting to be backed by the community where they think they belong.
I agree that
which is indeed an extremely important directive for our current weak base, but the exection context is important: One really cannot surpass the document quality for rpm and dnf, but Fedora Docs could strive to provide “what’s our repository structure” “How could you get a more managed experience instead of downloading .tar.gz if we don’t have it in repo”. These experiences from other first-hand distro users do exist in many Fedora discussions, but they are often drowned in the quantity of postings, and are hard for other users to reference.
For example, we may compare how Flatpak is documented on ArchWiki and Fedora Docs. As a crucial part of the Fedora application management experience, some command-line management and concepts, such as sandboxed environments and permission granting (at least a mention of Flatseal?), are more or less required for Fedora users with any proficiency.
In ArchWiki, although ArchLinux is not really coupled with it, we still see a list of user-friendly How-To on how to achieve what they may want, and a list of very common quirks and fixes specific to the environment a general Arch user may be in.
But in Fedora Docs, all we have is an incomplete, scattered packaging guide, which has nothing to do with 99% of users, and serves almost no use for the last 1% who would try Flatpak packaging, see the quality of the document, then turn to consult Flatpak document (which is exactly what they should be doing, as the packaging is distro agnostic, downstream could never compete with upstream document quality on this)
Fedora Docs is not written for users - That’s what mattered for the quality. Many user who wish to contribute to the collective knowledge base do not feels Fedora Docs is the place to go, and the higher barrier is just what hinders it more.