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.
Analysis of the current Fedora documentation
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.
An improved content concept
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).
How will it look?
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.
How we are planning to proceed
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:
- 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
How to gain further information and to bring in ideas and critique?
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
I don’t have any feedback directly on the proposed changes, so my apologies for straying out of topic but since we are talking about documentation, I would like to share something.
Overall, I think our documentation is very good. I am mainly interested in the packaging-related, and infrastructure sections and I have only positive things to say about them. However, what I really dislike is the homepage. Maybe it’s just me and everyone else loves it, but I can’t get over the concept of boxes. For however long I look at the page, I see headings and text, but I can’t focus on any of it and perceive it as one big mess (sorry). Let me elaborate:
Of course, that is my personal opinion, and I might be the only one, so it might be irrelevant.
Now, proposed solutions (ordered by preference, choose one ):
Once again sorry for going off-topic and for being quite negative.
You are not the only one who is dissatisfied with the current docs homepage design. It was up-to-date at the time it was introduced. But it is just “out of time” according to today’s expectations. Visually, you can argue about it, but the structure and the implementation are still solid and flexibly customizable.
Similar is true for other parts of the Fedora website, as well. Fedora launched a “Fedora website revamp” project last November. The project has started first with the download pages (see Fedora Workstation Front Page Revamp (first cut, looking for feedback!) - #34 by maiki - Fedora Discussion ). The project will gradually renew the design of the complete Fedora website. But this is a huge step and takes some time.
Therefore, we agreed not to put energies into the design now, which will be changed in a year or so for all Fedora sites anyway. But we will have to make some adjustments as we transition content. Your suggestions and feedback are welcome. Hopefully we can implement one or the other of your proposals while adjusting the interim solution and improve it further.
So, in the long run it will be something like no 1 of your proposals, and hopefully no 3 in the short term.
Thank you for the reply Peter, this makes sense. Sounds good to me.
That’s… not as true as it may seem, I’m afraid.
And that’s not necessarily as much of a commonality as it may appear to be, at first glance.
Over on Ask, a new user posted a question (back in April, though I didn’t see it until a few days ago) about installing via Anaconda. They were following along with the Installation Guide, and having troubles applying some information there. And unfortunately, that’s because it didn’t apply to them, at all. Which wasn’t at all obvious from reading it.
There’s a whole lot of “stuff” in that guide about how to boot a Fedora install image, mostly involving kernel parameters for configuring Anaconda. And all of that is still applicable, IF you’re installing Fedora by booting an install image.
But the recommended method of installing Fedora Workstation, for some time now, has been to use the Live Image as an installer. After it boots, there’s that handy window asking if you want to “Try Fedora” or “Install to Hard Drive” (which launches Anaconda). In fact, the Live Image is the only download presented on the main Workstation download page.
But somehow, the entire first half of the “Installing Fedora” section of the Installation Guide is still exclusively focused on booting and configuring an install image.
None of the provided install-configuration info is at all applicable when installing from the Live Image. It’s mostly about setting kernel command line options, none of which work with the Live Image. There’s the whole section on VNC, which is probably irrelevant too. I’m not even sure the documentation on switching consoles and etc. would still apply, when Anaconda isn’t launched at boot.
With the Live Image, you’d do any configuration by editing
/etc/anaconda/anaconda.confbefore launching it, something that isn’t covered in the Installation Guide at all AFAICT.
When I looked the other day (for the first time in years, probably), I was actually surprised to discover just how out-of-date — even misleading — the current docs are, for anyone using a Live Image as their installer.
Even for users installing via Anaconda, those two completely different paths to reaching it make for a very different experience.
I’m afraid I didn’t succeed in getting our message across clearly enough. Your description of the current state of the documentation corresponds exactly to our analysis.
The core of our message is: The texts “in themselves” are largely correct. But they are completely wrongly curated and wrongly titled.
The text titled “Installation Guide” is not useful to guide any Fedora installation. But it is useful as an Anaconda program description, i.e. as a reference guide.
For example, the workstation installation uses Anaconda to some extent. If you need detailed information about this part, the respective text from the current “Installation Guide”, in future renamed Anaconda Reference Guide, is indeed useful and helpful. This is the “commonality” I meant.
I wrote, 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.” Therefore, we’ll replace the current Installation Guide by links to variant-specific installation guides.
Unfortunately, for the asking user you mentioned above, the change doesn’t provide a real improvement. Simply, there is currently no “Fedora Workstation Installation Guide”. But at least it saves the user from having to slog through a text that pretends to be a “Fedora Installation Guide” resp. is wrongly curated as an Installation Guide.
Maybe you can condense the answers that ask.fp.o gave about this topic into a quick guide?
Continue the discussion at discussion.fedoraproject.org