egret/team-docs
1
0
Fork 1
forked from docs/team-docs
Code Pull requests Wiki Activity

intro-draft6

Browse source
This commit is contained in:
Eli Ridge 2026-06-28 01:35:56 +12:00
commit f10ccb34d8
1 changed files with 18 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

31
modules/ROOT/pages/contributing-docs/index.adoc
View file

@ -1,6 +1,6 @@
= Contribute to Fedora Documentation
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>
:revdate: 2026-03-07
:revdate: 2026-06-26
:page-aliases: contributing
:fedora-chat-url: https://matrix.to/#/#docs:fedoraproject.org?web-instance%5Belement.io%5D=chat.fedoraproject.org
@ -28,20 +28,20 @@ If you have some basic knowledge of Git and the AsciiDoc markup language, you ar
If not, take a few minutes to read xref:contributing-docs/asciidoc-markup.adoc[AsciiDoc for Fedora].
AsciiDoc and Git are easy to learn with time.
Okay, you are ready to start contributing to Fedora Docs, what next?
Okay, you are ready to start contributing to Fedora Docs - what next?
== First steps
* Create a link:++https://accounts.fedoraproject.org/++[*Fedora Account System*] (*FAS*) account
* Join us on {fedora-chat-url}["Matrix"] to say hello
* Join our {fedora-chat-url}[Matrix channel] to say hello
* Sign the xref:legal::fpca.adoc[Fedora Project Contributor Agreement].
To sign the agreement, go to your link:++https://accounts.fedoraproject.org/++[*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 https://forge.fedoraproject.org/docs/tickets/issues[docs issue], or bring your own docs issue, and get involved.
* Pick a https://forge.fedoraproject.org/docs/tickets/issues[docs issue], or bring your own docs issue, and get involved.
We welcome all types of contributions, big or small.
=== The contributor journey
Figure 1 provides an example overview of a contributors journey. But our approach is flexible.
Figure 1 provides an example overview of a contributor's journey.
.Example journey
image::int-journey.png[]
@ -51,7 +51,7 @@ image::int-journey.png[]
=== 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.
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.
@ -93,7 +93,8 @@ AsciiDoc can be written with almost any text editor or word processor.
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) triggers contributors, members, or board members applicable to the given repo to start the review process.
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.
@ -101,6 +102,10 @@ The flow of the review process is illustrated in Figure 3.
.General review process
image::int-review.png[]
=== 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 {fedora-chat-url}[Matrix channel].
== Editing approaches
There are two options for editing: locally on your machine, and directly on the Forge web interface.
@ -112,11 +117,10 @@ Here is a comparison:
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.
- See a live preview of your work exactly as it will appear in the final product.
- Work on multiple files and repos at once.
We encourage first time contributors to give the local workflow a go.
While there is a lot to learn, the power and flexibility of editing locally will be rewarding.
While there is a lot to learn when editing locally, the power and flexibility it provides will be rewarding.
Refer to the xref:contributing-docs/tools-edit-local-clone.adoc[Local workflow] guide for further information.
@ -130,7 +134,7 @@ Edits can be made directly on the Forge web interface. These are best suited for
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 crossreferences are not compiled correctly.
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 xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge] guide for further information.
@ -148,6 +152,7 @@ Some examples of contributions include:
== Larger contributions
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.
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 {fedora-chat-url}[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.