Contributing a new documentation sites

This section describes how to add a complete new piece of documentation that covers a new area in its entirety. This spans several pages and is usually associated with the creation of a new, dedicated repository. A local working environment is best suited for this. But it is also possible to use the GitLab web IDE.

The following text is slightly outdated, does not take into account the GitLab repositories and still needs to be adjusted.

This section describes how to create and publish new documentation to the docs.fedoraproject.org website. Before you start following this procedure, review all the requirements listed in Prerequisites.

Before creating a new documentation site, consult the Discussion forum first. This is to make sure we can publish your work and you do not waste your time.

  1. Clone the template repository: https://pagure.io/fedora-docs/template

  2. Create a new repository for the new documentation set, or ask someone to create one for you. You can host this repository anywhere but it is recommended to host it on pagure.io where you can reuse Fedora groups to control write access to the repository. Depending on the topic, it may also be best to host it under fedora-docs.

  3. Clone the newly created repository for your content set.

  4. Copy the contents of the template repository (without the .git directory) into the newly created repository or import the commit history from the template repository.

  5. In the new repository, edit the antora.yml configuration file in the repository root. The file contains comments that point out which parts you need to change. At a minimum, always change the name and title.

  6. Additionally, edit the site.yml configuration file. Note that this file is only used when building a local preview of your content set - on the website it is overridden by the site-wide site.yml configuration. The only directives you need to edit in this file is the title and start_page.

  7. At this point, when the initial configuration is finished and the repository is configured with the correct name and other required directives, push these changes to the newly created repository (or make a pull request if you can not push directly). This set of changes will be required for any other contributions, so make sure they are in as early as possible.

  8. Fork the new repository, so you are not pushing updates directly into it.

  9. Start adding the actual ASCIIDoc content. While writing, make sure your new source files are included in the nav.adoc configuration file of the module you are using (./modules/ROOT/ by default, the location will change based on what you configured in antora.yml earlier). Also make sure to use local preview often to check your markup.

  10. Once you finish, commit your changes and push them to your fork.

  11. Use Pagure to make a pull request from your fork to the main repository’s master branch.

  12. Someone will see your pull request and either merge it, or provide feedback if there is something you should change. Work with the people commenting to make sure your contributions are up to standards.

  13. Your new content will need to be published for the first time, and at the moment this does not happen automatically. Send an e-mail to the docs mailing list asking for your content to be published.

If nobody reacts to your Pull Request after 5 days, get in touch with the Docs Team. We might have missed the email for your Pull Request.

Want to help? Learn how to contribute to Fedora Docs ›