Adding new documentation to the site

This section describes how to add new documentation to the website and ensure it is published and listed somewhere. Before you start following this procedure, make sure that you fulfill all the requirements lited in Prerequisites.

== Before you start creating an entirely new documentation set, consult the mailing list to make sure your work is accepted by the project and you do not spend time developing docs that will be rejected in the end. ==

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

  2. Create a new pagure repository for the new documentation set, or ask someone to create one for you. The new repository should be listed 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.

  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 overriden by the sitewide 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 files 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 merge request from your fork to the main repository’s master branch.

  12. Someone will see your merge 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.

    If nobody reacts to your merge request in several days, try bringing it up on one of the weekly meetings, the IRC channel (#fedora-docs on FreeNode), or the mailing list.

  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.