In a recent Fedora Magazine article we shared about a new burst of energy regarding the Fedora docs. We already implemented various improvements and worked on a plan to generally improve and update Fedora documentation.
The latter will lead to far-reaching changes in Fedora documentation and is about to happen now and entail continuous changes over the next approximately 12 months. We present here our analysis, our content concept and our implementation planning. We hope for ideas from the community to further enhance the concept and for support to turn it into reality.
Currently, the documentation is structured by releases. With each release, we create a new version of the documentation. In fact, however, the differences between the variants – the Editions, Spins, etc – are much bigger than between the releases. It is impossible to write an installation guide that covers all variants. You would get 5 or more completely different guides that happen to live at the same address or in the same book. Even between Workstation and Server, both of which use Anaconda, the differences are too significant. Consequently, some variants have already started to create their own installation and administration guides.
If you have a look at the current installation and administrator’s guides the content isn’t bad or wrong, in large parts not even outdated. But it simply no longer apply completely to one of the variants. It has lost it’s objective. And that’s what makes these guides so strange and uneasy to read.
Despite all the differences, there are also commonalities. Several variants use the Anaconda installation tool, for example. While the variants provide instructions on how to use the tool specifically for this variant, we additionally need a description and explanation of the tool itself, its functions and modes of operation.
And besides those issues both guides are a large, monolithic block of text. They are in the format of a book rather than a website. Such an item is hard to maintain und to keep up-to-date, even when only parts of the content change.
As the most important and visible change we replace the release-based focus with a focus on our variants. This has several consequences
- The center of the docs home page focuses on our editions and our spins.
- The previous Fedora Linux boxes, named after releases, are combined into one “Fedora Linux” box spanning the variants, whose weighting is graphically emphasized. It keeps to be the central entry point.
- The “Fedora Linux” box no longer contains an installation guide, but a section “getting started” which describes the stucture and point to the correspondig variant’s installation guide.
- Additionally, there is a new “Fedora Tools” box. It contains a set of reference style documentations of our tools and recommended administration procedure. These are based on the current installation and administrator’s guide, that are – after some adjustments – very well usable and useful – not as an installation guide, but as a tool reference.
- The tools reference docs are created in such a way that parts can be selectivly linked to or can be included by edition documentation (to facilitate the reading flow, but to avoid duplications).
There is an issue on pagure that describes the planning.
We have also created a mock-up that should provide a (hopefully useful) first visual impression.
Note, only the boxes that change or are new are provided with an active link. The others only perform a refresh. And all the texts in the mock-up are provisional and preliminary. They are only meant to make clear the idea and the central message.
We plan to work along along the following guidelines:
- Keep with the current design as much as possible or just as minimal as possible adjustments.
- (Re)use as much of the existing text body as possible to keep the workload within limits.
- Break monolithic text into smaller, self-contained articles.
- Break down the changes into small enough steps to allow rapid publication of changes and avoid long “latency” periods.
The timeline is currently still quite crudely projected:
Start to implement part 1 on staging, consisting of “Fedora Linux” and Anaconda Reference Guide (about the same as the scope of the PoC)
Publish part 1 on production
Publication of further smaller individual parts at approximately every two months
First, post your questions and suggestions on this post’s discussion page.
Furthermore we are ready to partcipate on a variant’s meeting, IRC or other, to discuss the plan.
And additionally we have scheduled 2 docs office hours at different days of the week and different times of the day to offer an opportunity to discuss the plan in detail.
Scheduled office hours:
- Tuesday June 7, 1500 UTC email@example.com
- Thursday June 9 1900 UTC firstname.lastname@example.org