Fedora Web-UI-based Install Guide for F39: Where to place it in the Docs? Separate Editions/Spins?

Project Discussion
1

The new Web-UI installer will be released earlier than I initially expected: it is aimed to have it already released as default installer for F39!

The goal is correspondingly to have a guide in the Docs before its release, even if the guide is not yet perfect: especially when Fedora has a new installer, users are more likely to search for a guide.

However, the new guide will be concise and its style will be more inspired by the 7-steps guide than by the past install guide.

Much of the new Web-UI is imho self-explanatory (it is comprehensible and simple). So readers of the guide will be more beginners rather than advanced users, and I expect beginners to rely on default configurations. Thus, I intend at the moment not to make a strong elaboration of Blivet (to customize partitioning) but only go to the point where the user gets a screenshot of blivet and what it is. I will expect that the audience of the guide will focus on defaults, and that users who customize partitioning are themselves able to understand the meanings of btrfs, ext4, and so on (in the end, Blivet is self-explanatory to people who know about file systems and such). At some point, I might add links to upstream docs for advanced users once available (e.g., for blivet). For users who customize (and who thus already have knowledge about partitioning and such), this type of docs is likely to be more helpful anyway.

It’s thus mostly to give users security and confidence when acting/installing, to give initial guidance and to provide an overview of what can be done in which stages, not to answer sophisticated technical questions on themselves. This is also easier to maintain over time.

However, the first question is: where to place it?

First of all, please let me know if anything I propose here conflicts with ongoing Docs plans. Consistency is gold in documentation.

I suggest to place it (comparable to the old install guide) at “Fedora Linux” → “Fedora User Documentation”. At this place, I would put it in between “Getting Started” and “System upgrade”. If necessary, I might adjust the end of the “Getting Started” page to seamlessly transition to the install guide. Alternatively, do you prefer if I place it not next to “Getting Started” but within “Getting Started” (which means next to “Fedora Downloads” within the “Getting Started” sub-category)?

The guide will be focused on Workstation for now, but since the graphical installations of editions/spins used to be comparable, I tend to NOT put it to the “Fedora Workstation” category. The latter is maintained not by Docs but by the Workstation WG anyway (afaik this is still true?), and since the Web-UI is the official installer beginning with F39, we can expect that it will also help users of other editions/spins, whose users could miss this supporting guide when it is placed in “Fedora Workstation”. At the moment, Web-UI seems released only with Workstation, but it is a matter of time until it will be introduced to other editions/spins as well.

Once Web-UI is also applied to other editions, I tend to add some boxes or comments at places where other editions differ (and if possible, also for the KDE Spin and Kinoite given their widespread use) to generally serve users of major editions/spins (except if you want to create separated guides for other Editions/Spins?).

Let me know your thoughts (especially if I shall place the guide somewhere else, if you prefer another structure/content or if you want to create separated guides for different editions/spins). Nothing is fixed yet.

I will check out the most recent version of Web-UI somewhen this or next week and in parallel create the guide. My plan is to get it done during September (I try to be done by 22nd Sept.). Since this is a major change, I will let you know once I have a draft to allow the possibility to review before I merge it to the published pages.

I will keep this topic updated about the development and about where to find current drafts. I will also monitor it for incentives.

Related GitLab ticket: Create Web-UI-based Install Guide (#6) · Issues · fedora / Fedora Docs / Docs Website / Fedora Docs Website · GitLab

@ngompa I have seen that the current F39 nighty build (20230904) of KDE still use the old Anaconda. I assume this will remain in the F39 release? Just to know how to consider and elaborate KDE in the guide in advance.

2

The only variant making the change is Workstation. The Web UI lacks too many features for any other variant to use at this time.

3

Hello @py0xc3 ,
I am not a part of the documentation team as it is currently, but have contributed to documentation for the project at various times. I think the start should be for what is using it, so likely the editions. The various SiG’s of the spins and labs and the emerging editions, should be involved I think since what they produce is affected by a changing installer.
As to where to put it, where do we put the current installation guide, it should be either an evolution of it or a clearly new installer (like it is) with a new doc for it. What does the Anaconda team say?
Also @pboy and @hankuoffroad have been heading up some documentation efforts that I wouldn’t want to hamper. Maybe @jflory7 can comment.

4

Thanks. Then I keep it focused on Workstation for now.

That’s the reason why I ask in advance :wink: I am not up to date of the current plans. Generally, the Web-UI install guide is planned for long, so I assume I would have been made aware if this is no longer intended. However, it has to fit / be tailored to the current plans, as you say :wink:

The lack of an applicable install guide was a major reason for complaints in the past. But no one had time to write / maintain something new back then. At some point, the old one was so obsoleted that we took it offline since it caused more confusion than value, but the plan was to get something new given that an install guide belonged to the things where explicit demand was measurable. Back then, I took the responsibility to create something once the Web-UI is out, but this happens earlier than I originally expected. So this is why I come up with the topic now :wink:

I am not sure if I get your point. I assume the SIG/WG collaborate with Anaconda (the team who develops the installer), but I have been not deeply involved in earlier stages except some minor testing. As far as it concerns me, I have been in collaboration with the Anaconda team since this guide is planned. They provided me with intermediate images and information so that I can prepare and know what to expect :wink: (thanks again @m4rtink for the support :))

Once the guide and the first web-ui release is out (hopefully, at the same time), I aim to keep the web-ui install guide aligned to and synchronized with the web-ui releases (and the editions that use it), but unless the current Docs plans need something different, I would keep it with a clear focus on the target audience described above.

5

Well, that probably the basic question. The answer is: We don’t plan with a “Fedora Installation Guide” or “Anaconda Installation Guide” anymore. And therefore, no installation guide belongs to the current Fedora Overview section at all. Any installation guide belongs exclusively to the competence of the Working Group of the edition in question. We discussed the factual reasons for this in detail about 1 1/2 years ago, and I don’t want to repeat that now. The essence can be found in my blog post.

The version intended for release with F39 refers exclusively to the Workstation Edition. So it is best, to write a Guide for Workstation. So I suggest you cooperate with Workstation WG and publish the guide in the Workstation section.

An alternative place is the admin tools section. This is for Edition agnostic reference guides, e.g. an Anaconda reference guide that explains the various menu items and program capabilities. But in most cases, we just refer to the upstream documentation. Some tools are used in a very Fedora specific way. This would be a case for an admin reference guide in this place.

Anaconda is a good example here. We used to have a “Fedora Anaconda Installation guide” which was in the end more or less an outdated copy of the upstream project documentation. It was interwoven with other parts of the documentation (which was also already outdated) that it was immensely time-consuming or even impossible to develop an update. No one took on this work, and so the existing documentation became more and more obsolete every year.

We do not want to repeat such a situation ever again. The differentiation of the documentation and the involvement in the Working Group is a means to avoid this.

6

Anaconda team (as written above) is in contact with Workstation WG and we already talked about documentation is one of the things which needs to be provided.

Especially the new custom partitioning solution needs more explanation with examples. Otherwise Anaconda is more simplified so it should be self-explanatory so the documentation don’t have to be so intense.

7

I am not sure if there is a misunderstanding. The decision to ask for a collaboration with Anaconda and to get a new install guide was made several months after your blog post of May 22 since these were two different decisions (?). I mean, in Sept 22 you put the new guide on the meeting agenda yourself and agreed to the approach, which included the collaboration :wink:

However, if the plans of Docs have changed to have no longer a unified guide at the “Fedora Linux” category but only publish what is provided by the respective WG/SIG, this has to be put to Workstation WG repos of course.

It remains a little hard to understand current Docs decision making/plans if one is no longer involved regularly in the meetings. Some central point of what is going on and planned would be complementary, especially when non-permanents or other teams are affected by decisions. My last information about that topic was from a May 2023 meeting and its related discussions [1] [2], so a few months ago, when a new install guide seems to have been still part of the plans, including a placeholder. Some possibilities to verify if past consensus/agreements still apply would be helpful, just in case a new team structure is established or so.

Anyways, for now I consider the Docs-team-related part closed. The affected documentation repositories are thus at least for now those of the Workstation WG only.

8

My original plan was to write something easy-to-maintain modelled after the How to make casual contributions :: Fedora Docs , just for the beginner users, who complaint about a guide in the past, to give them some overview of what is/will happen and to give them some security and confidence with minor elaborations and mostly pictures - as you say, that’s mostly self-explanatory. (Feel free to let me know if that can be complementary to your thoughts or if the Workstation WG plans/intends something different)

However, for everything beyond this simple guide, I preferred (as noted above) to link upstream Docs at the related places, such as to Blivet, which seems to not yet exist. Is it intended to create dedicated upstream Docs for the deployed blivet GUI or to also integrate that in the Workstation WG Docs repos?

9

According to our current Docs planing, we would write (or aim at) a Fedora Anaconda guide (not an installation guide) for those parts which are specific to Fedora or those without any or only insufficient upstream documentation. These would be placed in the Admin Tools location and provide partials, so the edition specific installation guides can either reference it or include it directly to improve the reading flow.

And we are still looking for authors for it.