Purpose
Vision
Flattening Fedora Docs Roller Coster Ride
Fedora Documentation is an important part of Fedora Linux and Fedora Project. On one hand, the Initiative will result in a broad, stable, well organized and active Docs community, able to cope with inevitable fluctuations from time to time. On the other hand it will result in a great improvement to the Fedora documentation, which has become rather sparse over the recent years, in terms of completeness, continuous updating, quality and integration of documentation and technical evolution.
For details see Bokoč, Petr; Boy, Peter: „Fedora Documentation: Where We Are, and Where We Want to Go (slide deck)“ (Flock 2025) and Boy, Peter: „Fedora Docs – current state and conclusions from our experiences“ (CommBlock 2025)
Mission
One one hand, we have to take intensive onboarding and community building measures through intensive promotion and advocacy for Fedora Docs on all Fedora communication channels as well as to lessen the barriers to contribute to Doc by improving contributors documentation, add instruction videos, flatten the confusing, highly tangled storage locations (possibly into a single repository), and enhance the local authoring tools. On the other hand we have to establish a sound workflow, building interactions of devs and QA with writers for specific documentation topics, establish regular in-person hackfests either on their own or in conjunction with other Fedora events such as Flock, and offer high quality online instructional lessons and workshops.
As a tool/project to set all these actions in motion, the non-edition-specific part of the user documentation is to be renewed and completed in terms of content, UX (categories and tags), design, accessibility and quality.
Objective Leads
- Co-Lead: Peter Boy
- Co-Lead: Petr Bokoč
- Executive Sponsor: Justin Wheeler
Time Frame
- 12 months starting about November 2025
- The planned timeframe only allows for limited measures for community building and improving Fedora documentation. A successful outcome of this initiative could lead to a new follow-up initiative to further strengthen the documentation community and the documentation completeness and quality.
Logic Model
Visual
| Inputs time, people, money |
Activities the work we do |
Outputs tangible results |
Outcomes measurable benefits |
Impact high level goals |
|---|---|---|---|---|
|
Co-leads (Peter and Petr) Council executive sponsor Justin Wheeler Aoife Moloney Marketing team Podcast team Mindshare Committee Design team Join team CommOps team Budget Hackfest Budgets for in-person meetings Budgets for relevant events (Fosdem, Flock, DevConf, ...) Interns/Outreachy mentored projects |
Promotion and Advocating Docs Community Initiative, Sparking curiosity and interest, Increase / rebuild Docs Team |
Blog posts, Fedora Magazine article. Podcasts, posts on discussion, Flock talk or workshop, Contribution to release party Institutionalization of regular “reports” in various formats on improvements achieved, meeting results, upcoming work, and specific requests for feedback—and thus repeated opportunities to contribute to Docs in small, concrete steps without barriers to entry and to influence the next steps in the improvement process through small, individual actions Re-establish a regular meeting |
Building up a strong and robust Fedora Docs community |
Significant improvement in the usability of Fedora
Removal of a major obstacle to wider user acceptance Improved standing and strength in the world of Linux distributions Better opportunities for new contributors to get started |
|
Restructure Docs Homepage to better address existing and new contributors, supporting better the Fedora 2028 strategy Lessen barriers for non-technical users to contribute |
A renewed docs homepage, see draft at https://pboy.fedorapeople.org/draft/ Decent instruction videos, optimizued curricula for online and offling workshops Renewed offline writing tool ASCIIDoc preview functionality and/or WYSIWYG editor integrated in Forgejo |
Better integration of Docs into the Fedora community | ||
|
Initiating (sub)groups for specific (exemplary, PoC) content topics (e.g. Kernel, Multimedia, etc) Initiating discussion about modified packaging guidelines Initiating discussion about modified Edition criteria |
Up to date and more complete Docs articles, specifically technically correct and up-to-date Links to documentation included in package's description More meaningful titles and descriptions in packages Docs included as part of test days (specifically kernel) A decent minimal documentation for every Edition |
Better integration of technology and documentation | ||
|
Discuss and analyse current Docs quality Restructure Edition agnostik docs using categories and tags and article types |
Establish decent article types e.g. how-tos, explanation, tutorial) Create templates for various types of Docs, review criteria and review guide, new more complete style guide New Landing page for Edition agnostric Docs (Working title: system Docs) replacacing and supplementing current Quick Docs and Administration Tools |
Increase Fedora Documentation quality | ||
|
Exploring Forejo Repo for automation capabilities |
Depending on capability:
|
Precautionary measures against fluctuations in the number of contributors |
Expanded
The exact scope of the output cannot be determined in detail at this point in time. Community building is a highly fluid process. It depends on how many team members can be attracted, how early they can be attracted, and what their skill profiles are. Instead of a fixed plan, communication must be continually ignited and emerging opportunities recognized and exploited. As little as details can be determined in advance, the more certain it is that such measures will lead to success. This is especially true in an environment such as the Fedora Project, where an organizational framework and a common interest already exist. The key is to steer the process from small, “unobtrusive” beginnings to establishing a regular topic of communication in the Fedora community.
Also, it is not possible to renew all documentation in a single year. However, the necessary structures, instructions, tools, and sample examples can be created. Which articles specifically receive an update depends on prioritization on the one hand and on opportunities that arise on the other.
In the Quick Docs section, based on inquiries and discussions on the Fedora communication channels, the first priorities are
- Kernel, booting, emergency measures
- Installation media
- Nvidia graphics adapters
- Multimedia
- Web tools
From the previous Administration Guide, these could be
- Anaconda
- DNF
- Updating / Upgrading
Stakeholders
Initial „foundation (starting) team“
- Peter Boy (co-lead, curation, writing, reviewing, community building)
- Petr Bokoč (co-lead, workflow, writing, reviewing, community building)
- Hanku Lee (QA, audits, reviewing)
- Chris Onoja Idoko (Design, community building)
- Hristo Marinov (Image based Fedora, containerization, reviewing, writing)
- Tomáš Hrčka (jednorozec) (Forgejo)
- Cornelius Emase (Forge programming, reviewing, writing)
- Eli Ridge (contribution guides, reviewing, writing)
- Mat Holmes (reviewing, writing)
- Philip Grant (reviewing, writing)
Initiative Team
- Mindshare Committee
- Design Team
- Marketing Team
- Fedora Join Team
- Forgejo Deployment Team
Milestones
| Milestone | Goal |
|---|---|
| November 2025 | Start of Initiative
|
| End of February 2026 |
Blog posts, Fedora Magazine article. Podcasts, posts on discussion, online workshop, Contribution to release party A new docs homepage alike https://pboy.fedorapeople.org/draft/ Improved Docs contriubution guides, spec. written documentation Final plan to use and migrate to Forgejo incl. new docs supporting functionality |
| End of May 2026 |
Regular posts on various Fedorta communication channes (incl. Podcast,YouTube) about Docs activities, results and new opportunities for Fedora users Additional online Workshops Docs Hackfest, online or attached to existing conferences / meetings Docs part of kernel testday for release 44 Preview of new Edition agnostic landing page Improved quality and completeness of the current Quick Docs contents (Howto, Tutorial) |
| End of July 2026 |
Regular posts on various Fedorta communication channes (incl. Podcast,YouTube) about Docs activities, results and new opportunities for Fedora users Beta / RC version of new Edition agnostic landing page Improved and completed Docs contribution videos and workshop curricula Renewed offline authoring tool Significant expansion and stabilization of the Docs team and topic-specific subgroups (kernel, multimedia, etc) |
| End of October 2026 |
Complete migration and renew of the administration part of documentatoin (descritpion, explanation, overview) Significant documentation additions to Fedora packages, links from package descriptions to relevant Fedora documentation Flock talk Docs hackfest in-person All Fedora documentation on Fedora namespace Final version of new Edition-agnostic landing page |
Relevant Links
- Fedora Blog 2021 „Fedora docs is about to change significantly! Check it out still in statu nascendi“
- Fedora Design Work
- Fedora Docs Quality
- LWN article „Improving Fedora's documentation“
- Flock 2023 talk „Fedora Docs – What are we planning for the year ahead and how you can easily contribute“
- Flock 2025 talk „Fedora Documentation: Where We Are, and Where We Want to Go (slide deck)“
- Fedora Blog 2025 "Fedora Docs – current state and conclusions from our experiences"
