Review system requirements

[aneta-petrova]

What changes are you introducing?

Streamlining the system requirements a bit, to phrase them as actionable steps and remove some duplicates I noticed.

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

The goal is to make the requirements easier to follow and to turn them from lengthy-ish descriptions into a sort of a quick "pre-flight" checklist.

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

This started with my noticing that we advise installing on a fresh system in 3 different places. What was supposed to be a very quick PR to consolidate that, turned into a slightly larger PR along the lines "while I'm here, why don't I try fixing up the whole section..."

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 1abac58 is available at theforeman-foreman-documentation-preview-pr-4070.surge.sh

The following output files are affected by this PR:

• Installing_Proxy/index-foreman-el.html
• Installing_Proxy/index-katello.html
• Installing_Proxy/index-orcharhino.html
• Installing_Proxy/index-satellite.html
• 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
• Installing_Server_Disconnected/index-satellite.html
• Planning_for_Project/index-satellite.html
• Quickstart/index-foreman-deb.html
• Quickstart/index-foreman-el.html
• Quickstart/index-katello.html
• Quickstart/index-orcharhino.html
• Quickstart/index-satellite.html

show diff

show diff as HTML

[aneta-petrova]

Hi @evgeni, can you take a look at these updated installation system prerequisites? Please let me know if:

1. they are okay for the standard installer
2. the list applies to the new installer as well

The next step for me would be to reuse these prerequisites in the new installer guide, which is why I'm specifically mentioning 2. as well.

[Lennonka]

Yeeeesss!
Great job, just a few nitpicks below.

[ekohl]

I certainly like this new style a lot more.

I was looking at the headers as well. We have "1. Planning Foreman server installation" but then most have "requirements" in the title. "Supported operating systems" is an exception for all, but Katello also has "Best practices for optimizing storage". Have you had a look at that, or is it out of scope for here?

Overall I'm wondering if "Supported operating systems" really is a System requirement. If you don't merge it in, I'd consider listing it before the system requirements.

[aneta-petrova]

I was looking at the headers as well. We have "1. Planning Foreman server installation" but then most have "requirements" in the title. "Supported operating systems" is an exception for all, but Katello also has "Best practices for optimizing storage". Have you had a look at that, or is it out of scope for here?

Right now, I'm going section by section (or at least topic by topic, if one topic is spread across multiple sections for example). Storage requirements + Best practices for storage were merged in #4096

After I'm done going section by section, I want to look at all the sections together in #4087 That will be a better time review if the sections and their headings play nicely together.

Overall I'm wondering if "Supported operating systems" really is a System requirement. If you don't merge it in, I'd consider listing it before the system requirements.

Merging it with system requirements is a good idea but because it likely wouldn't be a simple 1-2 sentence bullet point (the section actually contains quite a lot of text for Satellite), I'd like to look into it in another PR.

[aneta-petrova]

Thanks so much for your reviews @ekohl @evgeni @maximiliankolb @Lennonka! I believe I've applied all your feedback and now I'd like to proceed to collecting the acks :) Do you think you could help with that? I'm happy to address any other comments you might have to make sure we get this right.

[maximiliankolb]

style-wise LGTM.

[ekohl]

👍 but consider #4070 (comment) as an enhancement.

[Lennonka]

Looks great, but I live Ewoud's suggestion.

[evgeni]

[aneta-petrova]

Merged to "master" and cherry-picked:

c5157ba..d8815b7 3.16 -> 3.16