The plan is the (preliminary) result of a discussion by the Fedora docs team.

Analysis of the current state

The current Fedora documentation is generally viewed with some unease. An analysis comes to the following theses:

1. Looking through our existing documentation, the shortcoming is not so much in the individual texts, but the shortcoming is the curation of the documentation. We have good content (although in parts not up to date), but it’s not necessarily arranged in a way where it’s easy to find.

2. The basic problem is that the layout of the documentation pretends there is a unified Fedora, organized by releases. But in fact, Fedora is primarily structured by editions, even if they are built on a common base.
   This is particularly evident in the Installation Guide and the Administrator's Guide. The editions differ in such a way that neither an across-the-board installation guide nor such an administrator's guide is possible. As an example, both Workstation and Server use Anaconda but in such a different way that doesn't fit into one guide.

3. Particularly the two aforementioned guides are very comprehensive and monolithic. Such a structure is difficult and time-consuming to maintain.

4. Apart from those issues, very many articles or parts of articles are well suited and meaningful. Some need to be updated, but very rarely discarded completely. However, there are a lot of gaps that are waiting to be filled.

Basic principles of an adapted composition

1. Abandon structuring by releases and replace it by Editions / spins (or variants).

2. The central entry point continues to be a particularly emphazised Fedora Linux "box" (without release identifier) that explains the structure, refers to edition-specific documentation for installation and administration, includes the current and previous release notes, and provides an overview of where to find what.

3. The largest part of the site is taken up by direct access to the documentation of the editions and spins.

4. In addition to their specific documentation, there is a documentation of common issues and topics or generic tools with a clear structure:
   a. Tools cross-reference (focus explanation of principles, .e.g. dnf, rpm, Anaconda )
   b. Quick Docs (focus how-to resolve specific common tasks and issues, e.g. network conection)

5. Comprehensive documentation (Tools reference) is created in such a way that parts can be included by edition documentation (to avoid duplications, but to facilitate the reading flow) or can be selectivly linked to.

Implementation of the plan

1. Most editions already have documentation on installation and administration and can take over this function immediately without much extra work. Some minor refinements and adjustments may be desirable to achieve a coordinated approach, vocabulary, and typographic style.

2. Problematic are Workstation and Cloud, which, to the best of our current knowledge, have not created their own documentation. A temporary solution could be found for Workstation. In the case of Cloud, provisional reference could be made to old documentation (ca. 2016). Alternatively, the edition / spin would have to be dropped, at least initially.

3. Keep with the current design as much as possible or minor adjustments.

4. (re)use as much of the existing text body as possible to keep the workload within limits.

5. Break monolithic text into smaller, self-contained articles.

6. Break down the changes into small enough steps to allow rapid publication of changes and avoid long “latency” periods.

Proof of Concept

A PoC implementation (mockup) is using the example of the introductory "Fedora Linux" tile and a tile „Fedora Administration Tools Reference“ with Anaconda.

It is available at:
https://pboy.fedorapeople.org/fedora/

Timeline

• June 2022
  Start to implement part 1 on staging, consisting of "Fedora Linux" and Anaconda Reference Guide (about the same as the scope of the PoC)
• July 2022
  Publish part 1 on production

Publication of further smaller individual parts at approximately every two months