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.
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.
Recent Comments