Fedora docs is about to change significantly! Check it out still in statu nascendi.

May 31, 2022 / pboy / 5 Comments

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 fedora-meeting-1@libera.chat
Thursday June 9 1900 UTC fedora-meeting-2@libera.chat

Categories: Documentation

Tags: documentation

About the Author

pboy

Comments

frostyx says:
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:
- There are too many box sizes - In the current version, “User Documentation” section is alright, but in “Fedora Project & Community” section, the first line has 2 boxes, second line has 4 boxes, and third line has 3 boxes. Maybe it would be more readable if it was 2-3-4, but the 2-4-3 is just chaotic. The proposed version is even a bit worse because it changes the previously okay “User Documentation” section.
- Each row of boxes has a different height - by such a small amount, that it is not obvious at the first sight, but leaves you thinking if the height is the same or not (instead of reading the text)
- The different font sizes for blue and light-blue boxes are also unnecessary and distracting
- It resembles Metro from Windows 8 which was wildly unpopular
- It is much easier to orient within a vertical text rather than horizontal. That’s why source code files has hundreds of lines and nobody blinks an eye but write more than 80 characters per line and the patch doesn’t get merged :D. The same thing with webpages, even though we have ultrawide monitors, the page content is usually rendered within a ~1000px column.
- I don’t understand why something is in a blue box and something light-blue. Is it purely a design thing or does it hold some meaning?
- The homepage doesn’t look anything like the rest of the documentation, and always leaves me wondering if it is even the same website or not.
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 ):
1. Ditch the boxes, and make the homepage look like any other page in the documentation - with the left panel, breadcrumbs and everything. Show only those two/three sections with their explanations - “User Documentation”, “Fedora Project”, “Fedora Community”, and point to three subpages containing the sections that are in the boxes.
2. Ditch the boxes, and make the homepage look like any other page … Convert the sections into normal h2, h3, headings, and add TOC.
3. At least address the fixable quirks that I ranted about
4. Leave as is
Once again sorry for going off-topic and for being quite negative.
pboy says:

Jakub KadlÄík:

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.

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 ). 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.
frostyx says:

Peter Boy:

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.

Thank you for the reply Peter, this makes sense. Sounds good to me.
ferdnyc says:

Peter Boy:

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.

That’s… not as true as it may seem, I’m afraid.

Peter Boy:

Despite all the differences, there are also commonalities. Several variants use the Anaconda installation tool, for example.

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.conf before 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.
pboy says:

Frank Dana (FeRD):

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.

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?