Creating a Beginner's Guide to Fedora #8
Labels
No labels
category
antora
category
meta
category
onboarding
category
tools
docs
community
docs
docs team
meeting topic request
type
epic
type
task
good first issue
help wanted
?
needs changes
?
needs reporter feedback
?
needs triage
?
needs vote
scope
bug
scope
improvement
scope
new
state
approved
state
blocked
state
duplicate
state
invalid
state
wontfix
No milestone
No project
No assignees
8 participants
Notifications
Due date
No due date set.
Blocks
Reference
docs/tickets#8
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
@MatH and I would like to propose a draft for "A Beginner's Guide to Fedora". The motivation is to provide a document that people interested in Fedora in general can read to help with the onboarding process. Target audience (as the title suggests) are complete beginners. To keep the scope of the document manageable it will focus on one Fedora Edition and tries to cover the following areas:
This is just a first working draft. @MatH and I are currently writing the first draft and would like to present it here for discussion.
This would really help. I like it.
The first draft for review by the docs SIG is available here: https://cryptpad.fr/code/#/2/code/view/te8J4lq0fdMQKDs10Fh6E8BsbtGoWeMMt1hiAPh4nOA/present/
We should see whether Peter Boy @pboy thinks this beginners guide could serve as a printed booklet.
Discussed in 2026-02-24 Docs Team meeting.
We reviewed the draft provided by @cstrauf and @theprogram during today's meeting. The team appreciated the encouraging, beginner-friendly tone. We discussed how to best integrate this without stepping on specific Working Group toes or creating a massive maintenance burden on the Fedora Docs Team.
The consensus is that we shouldn't create a whole new SIG for this. Instead, we propose setting this up as a new Antora component (e.g.,
docs.fp.o/users) with its own modules. This gives user-focused content a permanent home and makes it easy for the Ask Fedora folks to contribute directly to the knowledge base. @theprogram will be following up here with more detailed summaries of our structural approach.Thank you all for the time in the meeting yesterday.
In summary:
Yes, our 2026 guide is headed in the right direction and we can work on the final draft.
The guide is a 'beginners guide' rather than a 'KDE guide'
We can replace the excellent but slightly outdated 2018 Beginners Guide with this 2026 Beginners Guide, and
a) produce a printable PDF to be distributed at events
b) publish a version online, somewhere in the Fedora Docs
We need to find a home on doc for the guide. Justin has suggested making a new Antora module and essenitally a new 'beginning user' section in Fedora Docs.
While I like this idea, I will first investigate whether we can slot the Beginners Guide into another area - this is to minimise potential work and not multiply entities beyond necessity.
If we cannot slot the guide into an existing space - we will consider what type of team or user group could manage the 'beginning users' into the future.
At this time, @cstrauf and I @theprogram can commit to keeping the guide up-to-date for two years. In this time - 4 Fedora releases - I do not see much changing that will need to be updated.
Thank you for working on this!
A couple of suggestions, trying to come from the POV of a beginner:
Should we cover, within this document, more detail of how to update the system? (At present we link out to a page in the Fedora KDE edition docs, but don't include any detail in the Beginner's Guide itself). Motivations for this:
Should we cover dual-booting with Windows? Of course our ideal endpoint would be that the user moves entirely off Windows, but I suspect a lot of users won't be ready to make the jump without dual-boot as a bridge.
We would want to mention:
We can wrap it in a general narrative that we can't control the behaviour of Windows (instead we take a defensive attitude by equipping the user to fix problems that may arise), and that we encourage users to use dual-boot as a transition period to get their computing fully onto Linux.
To be clear, I'm happy to contribute these, not just bring you more work!
Thanks PG,
We have a new version (I'll get you all a link soon!),
In it we have covered updates via Discover and via CLI.
RE: Dual-booting - we are already at around 6500 words, and trying to get the guide to 6000 words.
For this reason, and that dual-booting can present unexpected problems I vote to leave it out.
We could link to a dual bootiing guide possibly - so authoring or updating dual-boot iinstructions on Fedora Docs would be my preferred route.
At this time, the Guide shoes users how to test Fedora via the Live USB method.
Cheers,
Mat
The "Gaming on Linux" section needs to mention Steam. It should specifically mention that even if a game doesn't run "out of the box", you can right-click the title in your library and pick a different Proton version which might help. I've actually come across Steam games that were supposedly Linux-native that crashed on startup, but switching to the Windows version and running it under Proton fixed it.
The guide should also have an explanation of open-source philosophy, from both a right-wing and left-wing POV, because you can explain it from both sides. I'd put it at the end, into the Glossary, so we don't bore the readers with political stuff upfront, it should just be there for those who are interested in it.
The left-wing POV is pretty common - it's basically communalism, communism even: From each according to his ability, to each according to his needs.
The right-wing POV is a bit more obscure, but basically the idea is that open source and open standards enable competition, they prevent vendor lock-in.
The reason we have not included Steam is that it is a proprietary, almost monopolistic, for profit service. It also requires enabling RPM Fusion repositories - which for an arguable reason we have decided not to do.
I certainly don't doubt that many users will want and use Steam - but it is very easy to look up - I would say any gamer could do this.
The Wine version point is a good one, I will ensure that the Lutris section mentions this.
I don't think that explaining political reasons is necessary because people who start reading / using the guide are already interested in Linux and don't need convincing. Political reasons are definitely interesting but the topic strikes me as more of an essay topic (maybe for Fedora Magazine) than a guide topic.
Where should we put the Guide on the docs.fp.o website?
We could link it from the homepage https://docs.fedoraproject.org/en-US/docs/
or from the Fedora Linux section https://docs.fedoraproject.org/en-US/fedora/latest/
or from the next level down 'Getting Started' (although that section has many different ways to 'get started' and is somewhat 'buried' for a real beginner to find.) https://docs.fedoraproject.org/en-US/fedora/latest/getting-started/
If we could discuss this at this weeks meeting that would be good.
And what team's repo should the content go in?
It would probably be best in Docs Team repo - but if the Docs Team doesn't want to 'own' the content past the two years Christian and I will keep it updated - then I can probaby put it in Join SIG repo, as we have a lot of people that come there and want to help out on an 'easy' docs project.
Just an addition from me:
@pboy Just to clarify: your bullet points concern future guides / a series of guides that are more detailed than "A beginner's guide...". Or are you saying that we shouldn't publish the beginner's guide in its current form but rather rework it into a series?
Responding to Peter,
"I would like to get it as a starting point and model for a series of “A beginner's guide ...”. In this case, for a specific desktop, either workstation or KDE. Workstation is in much a bigger need for documentation. Their current docs is the weakest of all (but they are the most widely spread)"
It would be a good 'easy fix' task from someone who comes in via Join SIG (where I contribute a lot).
However - having more than one Beginners Guide means more chance of 'choice paralysis'.
" In another guide, I would like to cover Fedora Server or Fedora Home Server spin-off and/or an atomic Desktop."
I personally am not interested is writing an Atomic guide. Someone can fork the project and do that if they wish.
"In my opinion, it should be as specific as possible for one of our “deliverables,” i.e., instead of thematic breadth, thematic depth for a use case."
"I would like to have it as a download option as part of the docs introduction (the wide box on the top) and a printed version as "swags" on our various booths. E.g. this year at Froscon in August. The print may be managed by the local ambassador group."
Having local Ambassador teams print it is probably the cheapest option. I was thinking an A5 PDF, so it could be printed on A4 paper folded in half. I would like some help by a pro with the page layout - I asked in Design SIG but no-one got back to me there. I will ask again.
@theprogram wrote in #8 (comment):
As a member of the Server WG, I can start to work on a 'Beginners Guide to Server'. The Server WG has a fair amount of documentation that is fairly in depth and covers a lot of topics, but we seem to lack a 'Beginners guide" type document.
@pboy Thoughts on this?
The guide is basically finished.
Can someone help me upload it to a repo here in Docs Forge, so we don't lose momentum.
I will be on the road later this week, so I want to get it done ASAP.
@pbokoc suggested on matrix to maybe add a beginner's guide repo under docs.
It would be great if we could get a positive vote on this to give a guide a real home. :)
I pushed a first version of the Beginner's Guide to https://forge.fedoraproject.org/docs/beginners-guide. I'd appreciate if you guys could give @theprogram and me your feedback. Cheers!
Discussed in 2026-04-07 Docs Team meeting.
The Beginner's Guide has been successfully converted to AsciiDoc and is currently in a 7-day proofreading period. The team has agreed that the language is suitable and that the guide will eventually be linked directly from the front page of the Fedora Docs website.
Call to Action: Please leave any pre-publishing feedback, formatting suggestions, or factual corrections directly on this ticket over the next week.
Once @pbokoc completes the final review next Monday and the guide is published, this ticket will be closed. Moving forward, all future bug reports and feature requests should be filed directly on the Beginner's Guide Forgejo repository.
All done.