intro-docs-contrib (#59)

WIP pull request for ticket [#11](docs/tickets#11), the introduction page for contributing to Fedora Docs.

Summary of changes so far:

- added small motivational paragraph
- suggest title streamline
- updated editing approaches to encourage local workflow
- reordered tools to have local workflow as the first item
- added links to local and web editing guides
- added visual contributor journey diagram
- added explanation diagrams for the site and for review process
- added various other explanations
- general revisions
- removed tool section on direct edit to upstream

Co-authored-by: Eli Ridge <>
Reviewed-on: docs/team-docs#59
Reviewed-by: Peter Boy <pboy@noreply.forge.fedoraproject.org>

modules/ROOT/nav.adoc

@@ -4,25 +4,26 @@
 ** xref:organizational/meetings.adoc[Docs Meetings]
 ** xref:organizational/workflow.adoc[Docs Workflow organization]
 
-* xref:contributing-docs/index.adoc[Contribute to improve and expand Docs articles]
+* xref:contributing-docs/index.adoc[Contribute to Fedora Docs]
 
 // xref:contributing-docs/contrib-existing-documentation.adoc[Contributing to existing documentation]
 ** xref:contributing-docs/contrib-new-documentation.adoc[Create a new documentation module]
 ** xref:contributing-docs/contrib-quickdocs.adoc[Contributing to Quick Docs]
 ** xref:contributing-docs/contrib-release-notes.adoc[Contributing to Release Notes]
 
-** Contribution Tools
+** How-to guides
 *** xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge]
 *** xref:contributing-docs/tools-edit-local-clone.adoc[Edit locally]
+*** xref:contributing-docs/tools-vale-linter.adoc[Check edits with Vale]
+
+** Legacy guides
 *** xref:contributing-docs/tools-gitlab-howto.adoc[HowTo for casual contributions (for GitLab-based pages)]
+//*** xref:contributing-docs/contributions-quick-repo.adoc[How to contribute to Quick Docs repo]
 *** xref:contributing-docs/tools-web-ide-ui.adoc[How to profoundly use GitLab UI for document maintenance]
 //*** xref:contributing-docs/contributions-quick-repo.adoc[How to contribute to Quick Docs repo]
 *** xref:contributing-docs/tools-file-edit-pagure.adoc[How to edit files on the Pagure Web UI]
 *** xref:contributing-docs/tools-local-authoring-env.adoc[How to create and use a local Fedora authoring environment]
 *** xref:contributing-docs/tools-localenv-preview.adoc[How to run a local preview]
-*** xref:contributing-docs/tools-vale-linter.adoc[How to check documentation style with Vale]
-
-
 
 ** xref:contributing-docs/style-guide.adoc[The docs style guide]
 ** xref:contributing-docs/asciidoc-intro.adoc[AsciiDoc for Fedora]

modules/ROOT/pages/contributing-docs/index.adoc

@@ -1,92 +1,158 @@
-= Contribute to Improve and Expand Docs Articles
+= Contribute to Fedora Documentation
 Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>
-:revnumber: F36 and newer
-:revdate: 2023-05-01
+:revdate: 2026-06-26
 
 :page-aliases: contributing
+:fedora-chat-url: https://matrix.to/#/#docs:fedoraproject.org?web-instance%5Belement.io%5D=chat.fedoraproject.org
+
 
 [abstract]
 ____
-This document explains how to work with the publishing system used to build the Fedora Documentation website. It will guide you through contributing to existing documentation as well as creating completely new content sets and publishing them in the English originals as well as any possible translations.
+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.
 ____
 
-There are many different ways to contribute to Fedora documentation. Some of them are designed to enable contributions without technical knowledge about Web Content Management Systems and about how to store and manage your contribution. The tool takes over all these issues for you. It enables authors to concentrate on the topic at hand.
+== The purpose of documentation
 
-Please check us out. If you come across a documentation page that contains an error or inaccuracy, use one of the casual contribution tools described below to improve the page. If you have any questions, please do not hesitate to contact the Docs team.
+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.
 
-Local authoring tools are designed to provide a powerful working environment for accomplished authors. They enable efficient work even on large complex interrelated text collections. These tools are aimed at experienced authors. 
+== What skills do I need?
 
-== How it works
+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 xref:contributing-docs/asciidoc-markup.adoc[AsciiDoc for Fedora].
+AsciiDoc and Git are easy to learn with time.
 
-Fedora documentation uses Antora to build and manage the Web site. Documentation is fairly static content, with occasional updates from time to time. This is exactly what Antora specializes in. It gathers static text documents and transforms them into a complete Web site, including navigation, links, formatting, positioning, adaptation to different output devices, etc. For more general information about the Antora publishing system, see the https://antora.org/[Antora website] and https://docs.antora.org/antora/latest/page/[Antora documentation]. 
+Okay, you are ready to start contributing to Fedora Docs - what next?
 
-As a writer, you concentrate on the content and write away.
+== First steps
 
-=== The general procedure
-
-The 4-eyes principle applies to the Fedora documentation. A different author reviews each contribution. When you complete your text or text modification, the system creates a "Pull Request" or "Merge Request" to integrate your text into the documentation body. This triggers other authors, board members or members committed to the part of the documentation body in question, to start a review and either initiates an inclusion or starts a discussion. Allow 2 to 3 days for an answer to a request.
-
-=== Some technical background
-
-Fedora uses _AsciiDoc_ to format text in a simple and efficient way. It closely follows natural writing styles in everyday notes for structuring and highlighting. In this way, you can use any editor, including almost any word processor that can edit and save AsciiDoc Text.  More about this below.
-
-The AsciiDoc text document is stored in a series of Git repositories. This is a system especially popular among software developers, but also very capable for managing text documents. Git encourages and facilitates the use of the 4-eyes principle by a "Pull (or Merge) Request Workflow". You only need to worry about the details of this workflow if you want to set up a local work environment intended for professional and frequent contributions. All other tools take care of the necessary steps in the background. 
+* Create a link:++https://accounts.fedoraproject.org/++[*Fedora Account System*] (*FAS*) account
+* 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 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.
 
 
-== Prerequisites
+=== The contributor journey
+Figure 1 provides an example overview of a contributor's journey.
 
-The only requirements for contributing documentation to Fedora Docs are:
+.Example journey
+image::int-journey.png[]
 
-* link:++https://accounts.fedoraproject.org/++[*Fedora Account System*] (*FAS*) account.
-* GitLab account
-* Must have signed https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement] from FAS. To sign, 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/
-* Basic knowledge of *AsciiDoc* markup language (see xref:contributing-docs/asciidoc-markup.adoc[AsciiDoc for Fedora])
+== 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: icon:edit[] - 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.
+
+.Website basics
+image::int-antora-site.png[]
+
+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.
+
+.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.
+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 xref:contributing-docs/tools-edit-local-clone.adoc[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 xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge] guide for further information.
 
 
-== The tools
+== Contribution types
 
-=== Quick way: 'Edit' button
+Some examples of contributions include:
 
-- Make changes to a single file for minor fixes directly from web UI of Git forge.
-- Write access to upstream repo required.
-- Use it as an exception (without review process), rather than a recommended option.
-   
-=== Easy way: Web IDE of Git forge
+- correcting small errors
+- adding, removing, and modifying links
+- revising existing pages
+- writing new pages
+- translation
+- general ideas to improve the docs
 
-- Make changes to multiple files directly from web UI of Git forge.
-- No need to install anything in local computer or run Git commands in terminal.
-- Pull Requests for review process (Merge Requests in GitLab)
-- You do not need special permissions or write access to the original project.
-   
-=== Flexible and advanced way: Create a local writing environment
+== Larger contributions
 
-- Work with multiple files and repos offline at your pace using your choice of text editor and terminal.
-- You can build and render the pages locally to test your changes using Podman container.
+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.
 
-== Typical ways to contribute
-
-One can distinguish several typical types of contribution to Fedora documentation, for which the available tools are suitable in different ways.
-
-There are many ways for various types of contribution. For example, typo fixes, adding short information or a link, update an article, write a new article.
-
-=== Update an existing documentation page 
-
-This task involves minor changes. For example, typo fixes, adding short information or a link, or a correction to the text. This type is especially necessary whenever the documentation needs to be updated for a new software version.
-
-The _File Edit button_ are convenient for this purpose. 
-
-=== Extend an existing documentation domain
-   
-This task involves adding one or more new chapter(s) or section(s) with several chapters. For example, adding another container technique to the documentation of containerization. 
-
-The _Web IDE_ is a convenient tool for this purpose. A local writing environment is useable as well, but may involve too much overhead if you want to contribute to just one document.
-
-It is highly recommended to present the plan on one of the Docs communication channels before starting. You may get suggestions and tips on content, but also on editing. For example, file structure and naming conventions.
-
-=== Introduce a new documentation area
-
-This task involves a new extensive subject area, such as new software or a new administration tool. For example, inclusion of several sections and chapters and the creation of a new, separate repository.
-
-For this type, setting up a local writing environment is useful and worthwhile.
-
-In any case, a prior discussion with the Docs team is necessary, if only to create the technical prerequisites.