User Documentation Maintenance
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 the documentation WEB site and stores all documents in various git repositories. The Fedora Server documentation is part of the Fedora Server repository in the docs subdirectory.
The pubic 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.
-
The most common way for casual contributions is to open a ticket and describe the issue, and maybe to make a proposal.
-
Edit the page in question using a Web-based page editor.
-
Set up and work in a local authoring environment on your desktop.
-
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.
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. Detailed information coming soon.
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. A separate page will provide detailed information.
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, server@lists.fedoraproject.org, 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 ›