At Flock 2025, @pboy and I had time for a face-to-face chat about Fedora Docs. We talked about a few things, mostly intended to imagine a plan to bring some fresh energy and contributions to the Fedora Docs project.
What I am sharing below is a summary of my handwritten notes from that conversation. In the interest of transparency and inviting more input from other Docs Team members, here is the summary:
Summary
This note summarizes a strategic conversation with @pboy and @jflory7 about the future of the Fedora Docs Team, centered on a community-driven “revitalization project.” The goal is to build a 2025-2026 roadmap that invites broad participation. The discussion highlighted three key initiatives:
Quick Docs Restructure: The existing Quick Docs sub-site, which houses “howto” content, will be restructured. The idea is to transform it into a proper knowledgebase with category-based Browse and tag-based search to improve content discovery.
New Landing Page: A new docs.fedoraproject.org landing page should be designed. The core challenge is to create a welcoming hub that effectively serves the distinct needs of its two primary audiences: users of Fedora Linux and contributors to the project.
System Administrator Guide Revamp: The existing System Administrator Guide will be significantly revamped and updated. This work involves researching and validating all content, ensuring it is accurate for the latest release of Fedora Linux, and documenting new features. This revamp is a strong candidate for a future Outreachy internship project.
Next Steps
These are not hard and definite actions, but they are an early idea of the work required to execute some of the ideas that me and @pboy discussed at Flock last month.
Note that these actions do not have a person assigned to them. This means that anyone can help out with any of these tasks! I do not have time myself to lead on these tasks, so the call is open for members of the Fedora Docs Team to help lead on any of these actions:
Initiate Roadmap Discussion: Create a public call-to-action (e.g., a Fedora Community Blog post or a devel-announce mailing list thread) to kick off the collaborative development of the 2025-2026 Docs Team roadmap and invite community members to lead and participate.
Enhance Quick Docs:
Propose the new knowledgebase structure to the community to gather feedback.
Engage the Fedora Design Team to scope the work for the new category-based theme and tag search functionality.
Create New Landing Page:
Initiate the project with the Fedora Design Team using Penpot.
During the wireframing process, explicitly map out and design for the user journeys of both end-users and project contributors.
Plan the System Administrator Guide Revamp:
In January 2026, begin the planning process to position the guide’s revamp as a formal Outreachy project.
Start a “rally call” to attract mentors and contributors interested in updating the guide.
Scope the work by creating an audit of existing content and breaking down the update tasks into “good first issues.”
This seems like a good suggestion for document management. Looking at other FOSS projects, it is clear that maintaining existing documents is important, and updates must be made according to changes (for example, software release lifecycle).
If I may offer my opinion, there are cases where documents do not keep up with changes, so I would like to see an easier method implemented as well, such as the one below.
Take a look at the top 5 questions that have been consistently asked over the past four years on Ask Fedora. For example, questions about best practices for system and data backup (snapshots). While many of these questions have been resolved thanks to the thoughtful answers from dedicated contributors, similar questions continue to arise. Wouldn’t it be helpful to document these? The document type might be a tutorial.
And yes, any easier method to manage documents is welcome. Unfortunately, I don’t get it what you mean with “easier method implemented as well, such as the one below.”
And yes, it is a very useful way to keep track of the most asked questions and create a document, indeed most likely a tutorial, about the topic. Unfortunately, the only way I know for now, is to write it manually (or ask AI for a draft). And that is not necessarily an easy way. Or do you know an alternative?
What I meant was that it is easier to create a new document than to modify and supplement existing documents in the docs. Of course, modifications and supplements are necessary, but I think some contributors may find it easier to create new documents depending on their characteristics.
Selecting the target for creating new documents is a bit tedious, but you can use the category filter in Ask Fedora to determine the target. It’s a manual process.
I gave a presentation on automation at another meeting last time, but I haven’t applied it in practice yet. I shared it before, but if you haven’t seen it yet, would you mind taking a look and giving your opinion?
Posting here to continue a discussion that started on a not really related thread. This thread here seems like it would be a more appropriate place to discuss it.
The starting point for this was the fact that the Getting Started page is more than 1 year stale - it was last updated for F40, still refers to the KDE Plasma edition as a “spin” and uses obsolete names for the Atomic Desktop editions.
The specific issues with that page should be resolved by accepting the outstanding merge request for that page.
But the broader theme I wanted to progress from that is:
How do we systematically ensure that the schedule for each release includes the work items to ensure that key documentation gets updated for that release, and we’re not left with outdated info on prominent user-facing pages?
The release work schedule does already have work items for docs (e.g. this plan for F43). However, this is focused on Release Notes, and it doesn’t cover the broader spectrum of documentation which is likely to change release by release.
So I suggest that in addition to the Release Notes, the release schedule should include:
Not every page will change with every release, but these pages should at least be reviewed to check the information is still valid, even if the only thing that changes is the review date shown on the page.
“Second-order” documentation changes, triggered by the changes that Release Notes describe.
As an example for F43, take the accepted change to enable auto-updates in Kinoite. That change will have a Release Note, but alsothis Kinoite documentation page will need to be updated. (It currently says “In the future, updates will be enabled and installed by default”, so that text will need to be tweaked to reflect that auto-updating has actually arrived.)
Item (1) seems quite straightforward - the scope of work is a review (and possibly edit) of a small, known set of pages. I hope this one is achievable for the F43 release.
Item (2) is harder because (I assume) we don’t have a great systematic way of mapping a change onto the affected documents. It probably involves some collaboration between the change owner and the Docs team to identify and edit the necessary pages. I can see that making this a smooth process could involve a longer piece of work beyond F43.
As far as I know, the dosc team is not in charge for the image based Fedora docs, i.e. bootc, CoreOS, IoT and Atomic Desktops. These docs are maintained by the relevant teams and the community.
In most cases related to image based systems, one of the change owners is also a member of the relevant team, and in this particular case he is a Fedora Kinoite and KDE maintainer. I’m not sure if this change is ready, but I’ll ask and if so, we’ll update the docs.
Sure. The question I’m trying to address here is “what’s the systematic fix to process that prevents Fedora releases from shipping with stale documentation?”
The release schedule already includes some docs-related tasks. (I understood the filter here to mean “tasks related to documentation” rather than “tasks owned by the Docs team” but not sure if that interpretation is correct.)
I’m advocating that we add tasks to the schedule to cover the work needed to ensure that when F43 releases, all relevant documentation has been updated.
You mentioned that the you and the change owner will make the necessary documentation changes for the Kinoite auto-updates, so my question is: is that task included on the release schedule?
(Kinoite auto-update was just one example of an F43 change: the overarching point is that it would be good to have these items on the schedule that the release managers monitor.)
First, let me clarify that when I say “image based,” I’m excluding Fedora IoT because I’m less familiar with that edition.
Docs related to Fedora image based systems are updated relatively frequently. For example, the Fedora CoreOS (FCOS) release cycle is approximately two weeks, and release notes are published. If an addition, update, or deletion is needed in the docs, this is tracked in the issue related to the change, and/or a separate issue is filed in the FCOS docs repo.
The other image based variants follow the standard Fedora release cycle, and the docs maintenance principle is the same as that of FCOS. Additionally, in all image based Fedora variants, the community is engaged and contributes to the docs.
I’m not entirely sure, but I assume that since this is an accepted change, it is covered in the schedule you provide a link to.