Create an overview of the installation procedure

[AkshayGadhaveRH]

Adding a module for installation overview with high level steps and links to each step.

JIRA: https://issues.redhat.com/browse/SAT-30834

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.15/Katello 4.17
• Foreman 3.14/Katello 4.16 (Satellite 6.17)
• Foreman 3.13/Katello 4.15 (EL9 only)
• Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
• Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
• Foreman 3.10/Katello 4.12
• Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• We do not accept PRs for Foreman older than 3.9.

Review checklists

Tech review (performed by an Engineer who did not author the PR; can be skipped if tech review is unnecessary):

• The PR documents a recommended, user-friendly path.
• The PR removes steps that have been made unnecessary or obsolete.
• Any steps introduced or updated in the PR have been tested to confirm that they lead to the documented end result.

Style review (by a Technical Writer who did not author the PR):

• The PR conforms with the team's style guidelines.
• The PR introduces documentation that describes a user story rather than a product feature.

[github-actions]

The PR preview for 0d4d1ae is available at theforeman-foreman-documentation-preview-pr-4120.surge.sh

The following output files are affected by this PR:

• Installing_Server/index-foreman-deb.html
• Installing_Server/index-foreman-el.html
• Installing_Server/index-katello.html
• Installing_Server/index-orcharhino.html
• Installing_Server/index-satellite.html

show diff

show diff as HTML

[AkshayGadhaveRH]

Working on fixing the build issues. Not ready for review yet.

[aneta-petrova]

Thanks Akshay! This works better than a list with links.

[aneta-petrova]

Discrete headings (like .Planning) will eventually be reported as issues by asciidoctor-dita-vale so it would be good not to add new ones. Thinking about how to make this section flow naturally, one option might be this:

Suggested change

	.Planning
	Make sure that your infrastructure meets the prerequisites for installation:
	During planning, you will make sure that your infrastructure meets the prerequisites for installation.
	This includes the following actions:

This is just a quick suggestion, feel free to tweak it :) The changes I'm making are:

• Replacing discrete heading with a descriptive "During planning, (...)". This adds more words but avoids the need for the discrete heading.
• This includes the following actions: helps prevent potential future situations when a new "action" might be added to planning but noone updates this list. (I'm not sure about the word "action" to be honest.)

What do you think? If this sounds good, can you look into updating the other discrete headings in a similar way? Whatever wording you choose, they should all be consistent.

[Lennonka]

Alternatively, I believe that this would be a valid use case for a definition list:

Suggested change

	.Planning
	Make sure that your infrastructure meets the prerequisites for installation:
	Planning::
	Make sure that your infrastructure meets the prerequisites for installation:

[AkshayGadhaveRH]

Went with Lena's suggestion.

[aneta-petrova]

I disagree with the current wording. Overview sections like this are difficult to maintain in the long term and if we really are adding one like this, the wording should be as future-proof as possible and should not duplicate a table of contents.

In my suggestions, I was thinking about what an overview section could look like so that it provides additional value over a table of contents and indicates that the list of actions in the overview is really just an overview rather than a complete list. In its current form, the PR has been steered back to duplicating a table of contents and introducing a maintenance burden.

[Lennonka]

I didn't realize. That's a valid concern.

[aneta-petrova]

Speaking in more general terms, this request came from Red Hat's downstream. In upstream, I've been mostly hearing about concerns that the installation guide is very long, which doesn't work well for upstream users. Therefore, I'm wondering: Should we only include the new overview for Satellite to address the downstream need, while excluding it from upstream to better accommodate the upstream users' needs?

[maximiliankolb]

Should we only include the new overview for Satellite to address the downstream need, while excluding it from upstream to better accommodate the upstream users' needs?

IMO there's value in this overview, so I am OK with adding it for all flavours.

[Lennonka]

It still sounds strange to me because "install" and "deploy" could be considered (partial) synonyms. (Or at least software installation is part of deployment, the way I see it.)

What about something like this?

Suggested change

	ifndef::foreman-deb[]
	* Install {EL} 9 on a newly deployed system.
	endif::[]
	ifdef::foreman-deb[]
	* Install Debian 12 or Ubuntu 22.04 on a newly deployed system.
	endif::[]
	ifndef::foreman-deb[]
	* Ensure a fresh installation of {EL} 9 on your server.
	endif::[]
	ifdef::foreman-deb[]
	* Ensure a fresh installation of Debian 12 or Ubuntu 22.04 on your server.
	endif::[]

Feel free to get a second opinion. I'm not sure how to say this either :)

[Lennonka]

Alternative:

Suggested change

	ifndef::foreman-deb[]
	* Install {EL} 9 on a newly deployed system.
	endif::[]
	ifdef::foreman-deb[]
	* Install Debian 12 or Ubuntu 22.04 on a newly deployed system.
	endif::[]
	ifndef::foreman-deb[]
	* Deploy a server with a fresh {EL} 9 installation.
	endif::[]
	ifdef::foreman-deb[]
	* Deploy a server with a fresh Debian 12 or Ubuntu 22.04 installation.
	endif::[]

Or even:

Suggested change

	ifndef::foreman-deb[]
	* Install {EL} 9 on a newly deployed system.
	endif::[]
	ifdef::foreman-deb[]
	* Install Debian 12 or Ubuntu 22.04 on a newly deployed system.
	endif::[]
	ifndef::foreman-deb[]
	* Deploy a server with fresh {EL} 9.
	endif::[]
	ifdef::foreman-deb[]
	* Deploy a server with fresh Debian 12 or Ubuntu 22.04.
	endif::[]

[ekohl]

I also see installing as a part of a deployment. For example, a deployment may also include creating the server (like a VM) with the right size. You then install the software on that server.

[aneta-petrova]

Feedback we are getting from users indicates that guides are long and hard to navigate. From how this PR has been developing, I'm not convinced that adding a new overview at the beginning will help solve either of these issues: the guide will get even longer, it will duplicate the table of contents and is also likely to get outdated over time.

Similarly, I'm not convinced that a section like this would improve navigation, which is the point of the original request, per "First-time customers sometimes lose their way during the installation process." mentioned in the Jira ticket. For example, if the overview mentions action items in imperative voice ("ensure this" and "configure this"), there is a risk users might start immediately thinking about how to make these actions happen -- but that's not what we want in an overview; that should come later in the procedures. Compare that with the Upgrade path overview section in the Upgrading guide, which tends to avoid describing action items and instead provides a high-level overview to prepare users for what awaits them.

If there really is a need for an overview in the installation guide, I believe we should find a way to make it much shorter and also be clear about the fact that it's just an overview and not a complete list of actions.

Alternatively, we could also focus on improving navigation through improving the table of contents. However, that's probably what we would only do for the future guide based on the new installer rather than the existing guide based on the new installer.