User Documentation Maintenance

The Fedora Server Edition working group, Peter Boy (pboy), Stephen Daley (mowest) Last review: 2025-11-11
Part of the Server Edition Working Group’s tasks is to create and maintain user documentation. This is intended to enable or facilitate users to use the services offered in accordance with our technical specifications safely and correctly. Here we describe the basic structure of this work and thereby enable all users to contribute to the documentation.

This article is awaiting final review!

Goals

We want to and maintain a Fedora Server Edition user documentation and keep it up to date on an ongoing basis that

  • focuses on the specific features and procedures of the Fedora Server Edition

  • also includes brief explanations and rationales that convey the meaning and underlying concepts

  • contains copy-and-paste capable instructions that allow even less experienced administrators to operate safely and reliably

  • refers to the upstream documentation for general information, where available

Organization

Fedora uses Antorra CMS to create its documentation website. To enable authors to contribute to web pages even without solid knowledge of web design, Antorra uses simpler texts written in AsciiDoc, which are automatically converted into complex HTML pages. These texts are stored in Git repositories.

The AsciiDoc source texts for the Fedora Server user documentation are located at https://forge.fedoraproject.org/server/user-documentation.

The public user documentation is available at https://docs.fedoraproject.org/en-US/fedora-server/

Contributions

Authors as well as users should be able to contribute to Fedora Server documentation with as little effort as possible and without technical hurdles. We provide several ways to contribute.

  1. The most common way for casual contributions is to open a ticket and describe the issue, and maybe to make a proposal.

  2. Contact the Working Group in our Matrix room.

  3. Edit the page in question using a Web-based page editor.

  4. Set up and work in a local authoring environment on your desktop.

  5. You may send us an email, e.g. while reading a document on our Web pages.

Open a ticket (problem report)

When reading a document, you see a "bug" button on the rightmost side below the blue top bar. Click it and you are forwarded to create an issue. Members of the Working Group are notified and will take care of it. However, you must have a Fedora account, so you can log in.

Write in the Fedora Server Matrix room

Open your Web Browser and visit the Fedora Server Matrix room. You can either use the Web Interface or switch to the Element App. This is an asynchronous communication channel. It may take some time for someone to respond.

Edit a page via a Web Editor

Besides the aforementioned "bug" button there is a button that stylizes pen and note. It leads to a web-based editor that can be used to make changes to this very page. These are not applied directly, but members of the documentation team are notified for a review. For detailed information see chapter Working with the Web based page editor

Working in a local authoring environment

For longer-term engagement, it makes sense to set up a complete authoring environment. It requires some preparations, but it provides the most powerful set of tools. The article xref:usr-docs-maintenance/local-authoring.adoc

Sending an email

If you can’t use any of the above options because you don’t have a FAS account, you can just write your suggestions or feedback in an email to the Fedora Server list, [email protected], or post a message on our discussion board. You have to register, but it is less effort than creating a FAS account. It’s best to use a form like "current version" - "proposed version". Suggestions will then be included in the text, or perhaps there will be follow-up questions.

Quality assurance

Prior to publication, each article should be reviewed. Such articles are available in our staging area and marked as "awaiting review" or similar.

Reviewer should:

  • check for technical and content accuracy. Contact the author in case of questions.

  • check spelling and syntax

  • refine the wording and phrases, especially in the case of non-English speaking authors

The staging area also contains articles at an early stage of development, allowing for early subject matter exchange and idea collection.

Furthermore, the published pages are mirrored, giving a complete impression of the later documentation.

Guidelines

The article What is good documentation for software projects? provides a good summary of what we want to achieve with documentation, although it is not entirely new.

Some pointers for articles:

  • Include of author(s), date of creation, last update, and the Fedora version used to test the examples.

  • Start with a short summary of the subject matter, objective and desired outcome. (one paragraph of 2-3 sentences)

  • Divide longer sequences into sections with subheadings and short explanations.

  • Provide each step with a brief explanation/justification, if possible, a general instruction structure and a concrete example.

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