Contribute to Fedora Documentation
Welcome to the Fedora Documentation Team. If this is your first time contributing to an open source project, Fedora Documentation is an excellent place to start. Whether you’re an experienced contributor or just getting started, your input is valuable and highly appreciated.
This page will explain the documentation tools we use and our review process.
The purpose of documentation
Why do we write documentation? Essentially, it is to help users get tasks done. If a Fedora Linux user can complete a task faster, more efficiently, or with greater ease, we are achieving our goal. Good documentation is critical to the success of an open source project.
What skills do I need?
If you have some basic knowledge of Git and the AsciiDoc markup language, you are ready to go. If not, take a few minutes to read AsciiDoc for Fedora. AsciiDoc and Git are easy to learn with time.
Okay, you are ready to start contributing to Fedora Docs - what next?
First steps
-
Create a Fedora Account System (FAS) account
-
Join our Matrix channel to say hello
-
Sign the Fedora Project Contributor Agreement. To sign the agreement, go to your Fedora Account, select "Settings" by clicking your profile image in the top right corner, and then select the "Agreements" tab. Alternatively, it can be found here, substituting your actual username: https://accounts.fedoraproject.org/user/your-username/settings/agreements/
-
Pick a docs issue, or bring your own docs issue, and get involved. We welcome all types of contributions, big or small.
How the docs work
Repositories
Fedora documentation comprises around 60 git repositories (repos), often with a different team responsible for a given repo. The repos are hosted across Fedora Forge, GitLab, and GitHub. Previously there was also content hosted on Pagure and the Fedora wiki. Many of the repos have now been migrated to Forge.
How to locate a repo
To locate a page’s source repo, press the edit button: - located on the upper right side of the documentation page itself.
Forks
A fork is your very own, personal copy of the main upstream repo. All editing is done within a fork. This allows you to make edits and experiment with the repo without it having any effect on the main upstream repo. By design, most contributors will not have access to commit changes directly to the main upstream repo.
Branches
A branch is a distinct line of development within a repo. It provides a reference point for a specific area that you are working on, and it means that edits on one branch will not affect another. The majority of the upstream repos have only a single branch, the 'main' branch. Some repos use branches for version control, i.e. documentation that applies only to a single release version of Fedora Linux.
Website
Antora, a static site generator (SSG), pulls source content from the repos and generates the Fedora Documentation website, illustrated in Figure 2.
The reason Antora is used is because it excels at compiling from multiple source repos to generate a unified site.
Source pages
Documentation text is written in the AsciiDoc markup language. AsciiDoc is used because it is the native language of the Antora SSG. It closely follows natural writing styles in everyday notes for structuring and highlighting. AsciiDoc can be written with almost any text editor or word processor.
About our review process
Fedora documentation follows the 4-eyes policy, meaning a second person (the second set of eyes) must review and approve a documentation change/addition before it can be merged to the main site. We do this to maintain accuracy and consistency across our documentation.
Opening a "Pull Request" (PR) initiates the review process. Reviewers will check for grammar, technical accuracy, style, and completeness. This will normally lead to the new or amended text being merged to the documentation website or a discussion on improvements.
The flow of the review process is illustrated in Figure 3.
Timeline for review
We aim to review and respond to PRs within seven days. If you haven’t received a response within two weeks, please feel free to send a friendly reminder in our Matrix channel.
Editing approaches
There are two options for editing: locally on your machine, and directly on the Forge web interface. Both approaches have different strengths and weaknesses. Here is a comparison:
Locally
Editing locally allows you to:
-
Edit large sections or even entirely new modules
-
See a live preview of your work exactly as it will appear in the final product.
-
Work on multiple files and repos at once.
While there is a lot to learn when editing locally, the power and flexibility it provides will be rewarding.
Refer to the Local workflow guide for further information.
Forge web interface
Edits can be made directly on the Forge web interface. These are best suited for:
-
updating small sections
-
adding or modifying links
-
typo and grammar fixes
This approach means you don’t have to install any new tools on your machine. It also does not require use of the terminal. However, it has some limitations if making larger changes. It does not allow a true test preview of the pages. Images and cross references are not compiled correctly.
Refer to the Edit a single page in Forge guide for further information.
Contribution types
Some examples of contributions include:
-
correcting small errors
-
adding, removing, and modifying links
-
revising existing pages
-
writing new pages
-
translation
-
general ideas to improve the docs
Larger contributions
The smaller a PR, the easier and quicker it is to review. If you would like to complete a major revision of a page, or write an entirely new page or section, reach out to us on the Fedora Documentation Matrix channel. This helps to ensure your time is wisely spent and allows others to weigh in on the direction that we take together as a project.
Want to help? Learn how to contribute to Fedora Docs ›