Remove Install Guide from main

Just a short spin-off from the recent #docs discussions:

I would like to delete the whole directory + content of the “Install Guide” from “main”:
/fedora/docs/fedora-linux-documentation/install-guide/-/tree/main/modules/install-guide/pages/install

Also, I would remove the whole category “Installing Fedora” with all sub-items from the nav.adoc.

Just to avoid misunderstandings: This is git, all data will remain stored in the history and the previous state can be reviewed and recovered at any time. So deleting it in “main” will not cause a loss of data. I just would like to have the Install Guide offline, unreachable and out of search engines.

Objections to the removal?

Supplement: If we start to do a clean-up, I would in advance create an “obsolete” branch to make access to the discarded data easier.

The problem I see is not so much the removal of the installation guide as the gap that the action would leave. If we are suddenly in such a hurry, we should replace the entire page with the content we have already announced and put up for discussion in the community. Possibly in a somewhat shortened and simplified form if we are in a hurry. But it must be clear and unambiguous that we are beginning to implement this plan. We can’t just leave a blank page there (although that is certainly better than the current misleading content).

The rush is certainly justified, but we shouldn’t do it entirely without a development plan.

I would prefer to take the proposed and discussed structure and put it into an MR that we can discuss and refine in the coming week, and then make the move “with style” next weekend.

Well, absence of information for the user is better than existence of confusing information against the user.

An alternative would be a page that mentions that a new one is in development.

However, we soon have to evaluate more: as long as there are pages that are comparable to the Install Guide, the Docs cannot be trusted because the user will be in a situation where they cannot identify what they are up against on each page. I will make a proposal in the next days about how a upstream-focused concept could be implemented we already talked about yesterday. But getting rid of things that are more confusing/misleading than informative has to go along with that.

That would be misleading information, too. Nobody is currently working on something like that. And due to the current structure, it is impossible to really deliver on the announcement.

What is wrong with my proposal?

At some point, we will need to have one again. That something is to come is not wrong imho.

I didn’t know about that. If we have an alternative for the Install Guide that is up to date, of course. Do you have a link about the discussion to review?

The alternative is Fedora Documentation :: Fedora Docs or better at the moment Fedora Documentation :: Fedora Docs and the text in the red indicated boxes. Maybe we have to further simplify it a bit. We wrote a mail to each Fedora Edition WG and to every spin etc. I wrote a blog article, and we held two office hours. There were some favorable comments and no negative reaction. So it is a valid plan we are entitled to follow through.

In both versions (btw, both contain the same Fedora Linux category; equal link), I can only find a “getting started” that still contains i386 architectures in “Fedora Downloads”, which is behind our current Docs, and a “Preparing Boot Media”, which seems to be widely equal to “Preparing for Installation” but without the first paragraph. It still contains the old information and images. There was also an issue that these media writer images are no longer up to date, although I have not checked every issue as it were too many. So it seems to be widely the same but with a few pages already removed, and without the corrections we already made since?

Getting Started :: Local Preview

Am I wrong here?

We have to be careful here. Given the condition of the Docs as they are, I am not convinced that no negative reaction implies a positive feedback. It can also imply the absence of attention. E.g., I don’t think that this was reviewed by someone who knows about Fedora’s architectures. Just as an example.

A bit. :slight_smile:

It is not a perfect text ready to get published, but a kind of mockup. I wrote it when we were a F35, so there is still i386 and armhpf. And the getting started is not an installation guide, but it introduces the existing installation guides and were to find it. That is the replacement for the current installation guide.

And the 2 alternatives are about the boxes on the home page, the first one is the “optimal” one which includes all editions, and the second one is an approximation to the real situation where we have no installation guide or any other documentation for Cloud and Workstation. But we have documentation for nearly all the other editions and spins.

But most important: we have something we can use to replace the current installation and admin guide and need not leave a blank page. We have to make some adjustments and updates, e.g. regarding i386, and we may have to leave something off, e.g. the mediawriter part. But again: we don’t leave a blank page, but we propagate what we have.

It might be a good idea to bring forward the work on the replacement and improve the team page afterwards.

We have rules, and one rule is, if no one objects it is considered as consent. And we had initiated a broad discussion, while a simple deletion of the guides was not discussed anywhere.

Generally, I’m just talking about the Install Guide (… at the moment).

Tbh, I don’t see the difference of this alternative to the current page. We have proven that we cannot maintain it (including this alternative), the pages seem to be widely equal to those we have (including the issues) and some are deleted. The latter is what I suggest for all, and the first contains the issues we are talking about: it may be even more confusing because this alternative tells first how to use a media writer version that no longer exists (it tells users that they will see Workstation, Server, Cloud; but in fact users will have at first the major choice of Official, Emerging, Spins and Labs). Then, after the user got this obsolete (and at the moment false) information, there is a hard cut: after preparing boot media (where they are already widely on their own because of obsolete information), there is nothing more about how to use this media. I don’t see an advantage to the current page.

Imho, giving the user no information is better than telling Fedora has i386, or telling them about media writer interfaces that no longer exist. I expect #11 applies to these pages as well (I just skimmed it). As long as our policy is to keep obsolete (which widely equals false) information online until we have something better, we cannot expect trust in the Docs.

Rough consensus does not imply positive feedback. It is dangerous to derive the latter from the first.

Which is why I started this thread :smiley:

That’s a misconception. We have “proven” that a unified installation guide is not maintainable and not creatable, for conceptual reasons. And we have decided to implement the alternative as proposed.

And I think the difference is obvious. We switch from one unified installation guide and administration guide to variant specific guides. But we preserve a common starting point for users, especially new users, where we provide guidance for getting started with Fedora. That’s the concept, and it’s really significantly different now than it was before.

Do not confuse implementation details with the underlying concept. Mediawriter is just an example that there are of course overlaps that can and should be documented together. For each of the variants, the distribution ISO must be transferred to CD or USB stick. This can be documented centrally and does not have to be done by each variant itself. And there are other examples.

Please, be fair. The text war written with F34 / 35 in mind. That time we had i386 and Mediawriter. Today we have not. We have to make the usual adaptations between releases.

And just delete is not the way to go. What is your proposal / plan to fill in?

Well, empty pages are not trustworthy, either. We must develop a plan to do it step by step in order of importance. And with a long range plan in mind. And we can’t “save the world” resp. Fedora in one go, unfortunately.

The structure is changed. The content with its issues is unchanged/unrevised. But opened issues and complaints were about the latter. As far as I see, the content was already outdated at the point when this alternative was discussed.

And at the first image, we show them already 3 possibilities, of which none is contained in the current media writer: they see 4 other possibilities. And this is how the current guides continue. I think starting with such impressions / confusions is a worst case.

I think the problem is in the latter. And this preserves issues in the first.

No. It was already outdated in F34. I think F31 was the first without i386/i686. The content is much older. My guess it that it was not reviewed/revised in the discussion. Anyway, these were just examples.

My suggestion would not contain empty pages.

However, I will make a proposal in the next days that is a bit more holistic (and easier to maintain) for a general guide, not just for the Docs (derived from the 7 steps approach). So also for the installation guide in the marketing material, which is also as of 2018. But I have to see when I have the time to formulate it. I already started to create the screenshots.

Sorry for that formulation. Now that I review it, I recognize that it can be interpreted in a mean way. This was not my intention. But my opinion is that absence of information is better than provide something that is confusing or obsolete/false.

Tbh, I start to generally question the past “agency of the Docs”. I didn’t know about such discussions & decisions. While there have been so many issues, obsolete information and clear indications that these types and amounts of docs can be neither maintained nor organized the way it used to be, it still seems these problems were ignored in order to take the limited time to discuss nice structures. I think the focus that used to be imposed is itself a problem.

Nevertheless, as there is obviously still need for discussion about the Install Guide issue, I will consider this closed for now. It was just an idea for an (likewise imperfect) interim solution.

Looking forward to your proposal for a general guide. I don’t understand the passage “not just for the docs” nor the marketing material installation guide, but let’s see.

Fedora has marketing material, which we distribute at conferences and conventions, e.g., at our own booths such as at the FrOSCon last week.

This material also contains a printed installation guide (a little booklet). But it is not the one we have in the Docs. The marketing material guide has a comparable approach to the 7-step HowTo. I think it is a better role model than the current Docs guide because the marketing one is “target audience”-focused (provide what is needed for the very group: only appropriate and necessary information provided tailored to the group), not redundant (e.g., available architectures are on getfedora anyway), generic (it contains what people need, which, e.g., excludes versions of GNOME that change with each release) but still focused on the images we have, and easy to maintain (if there is no major change in the installation environment, it will be screenshots here and there to change, not more). As I think this is easy to maintain (with a designated maintainer), it could be one for beginners (live image), one for advanced (everything), and maybe one for server.

Installation guides are the one thing where people cannot go upstream or switch to Arch Wiki, so this is critical and does not only need to be created once in a good quality, but kept up to date with each release (at the best with working with people upstream; anaconda, blivet, (cockpit,) etc.).

I hope I have time to sum it up tomorrow or on Monday. At the best, we can create something that makes also sense for the #marketing team. Maybe they have valuable incentives, too. If we can find a consent for something, I can take the maintenance.

don’t forget CoreOS, Cloud, IoT, Kinoite, Silverblue

And Everything-DVD is not meant to be used for installation, because you would miss various default settings that are specific for the variants. As an example, if you boot from Everything and select Server to install, you will get a different result than if you boot from Server DVD (unfortunately without any hint).

There was a discussion to drop everything DVD for that reason. On the other hand, Workstation WG is or was discussing to “occupy” Everything for Workstation to provide a way for mass installation in professional settings.