Review OS requirements

[aneta-petrova]

What changes are you introducing?

• Edits to the supported OS section
• Moving the supported OS section to the beginning of the installation prereqs

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

Some of this was suggested in #4070 (review), the rest is just to give users a bit smoother experience.

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

N/A

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.16/Katello 4.18 (Satellite 6.18)
• Foreman 3.15/Katello 4.17
• Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
• 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 8088971 is available at theforeman-foreman-documentation-preview-pr-4203.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
• 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

[ekohl]

I think this is mostly an improvement. I don't like that quick start becomes longer because of an additional header. It was already too long.

My ideal for quick start is that it fits on a single screen, without scrolling. Perhaps you the quick start guide can simply point to the regular installation guide for the requirements and drop both the OS and system requirements altogether?

[aneta-petrova]

My ideal for quick start is that it fits on a single screen, without scrolling. Perhaps you the quick start guide can simply point to the regular installation guide for the requirements and drop both the OS and system requirements altogether?

Is it still really a quickstart, though, if you ask people to read the full book elsewhere? I'll admit I still struggle with the idea of a quickstart guide. Is it something that's intended for testing and then users are expected to throw the result away and install again, this time properly? If so, then let's include the necessary minimum requirements for a very basic scenario without, let's say, any capsules or hosts (so just OS, memory, fresh system). In any case, that's what I'm trying now -- with a separate requirements module, just for quickstart.

Is this what you had in mind @ekohl? Although the changes to the quickstart in this PR were mostly accidental, I'm happy to try and improve that guide as well.

[ekohl]

Is this what you had in mind @ekohl? Although the changes to the quickstart in this PR were mostly accidental, I'm happy to try and improve that guide as well.

Looking at https://theforeman-foreman-documentation-preview-pr-4203.surge.sh/nightly/Quickstart/index-foreman-deb.html I'd drop the Operating system requirements and System requirements chapters altogether and simply link in the intro text to the real installation guide.

For Debian they don't add anything because Configuring repositories already has instructions for specific OS versions so IMHO that's already covered. On EL there is no such header so perhaps that's something to consider, but the URLs already say el9 so IMHO it's not a big deal.

[ekohl]

Is it still really a quickstart, though, if you ask people to read the full book elsewhere? I'll admit I still struggle with the idea of a quickstart guide. Is it something that's intended for testing and then users are expected to throw the result away and install again, this time properly? If so, then let's include the necessary minimum requirements for a very basic scenario without, let's say, any capsules or hosts (so just OS, memory, fresh system). In any case, that's what I'm trying now -- with a separate requirements module, just for quickstart.

It should be the quickest way to get a system up and running, without too many details. I think https://theforeman.org/manuals/3.15/quickstart_guide.html is still a decent example: on my screen I can see all instructions without scrolling. That last part is IMHO really important and something that the current guide fails. Mostly because the headers in this guide are very big and take up a lot of space. So do the tables.

[aneta-petrova]

Great, thanks for the information! My takeaway from the conversation so far is that for the installation guides, there are no significant objections to the changes introduced in this PR. It's the quickstart guide that needs a bit more work so I'll focus on that.

The goal is to keep the instructions for quickstart short. The goal is not to set up a testing environment that is expected to be discarded. In that case, I'm still concerned about skipping the prerequisites but perhaps that could be solved by transparently explaining the intention for the quickstart guide and by linking to the full installation guide. I'll work on a draft.

[aneta-petrova]

To summarize the latest state of proposed changes for the Quickstart's system requirements:

• They have their own file, separate from the main installation guide's requirements
• They list only the most critical items, linking to the full installation guide for everything else (such as less common scenarios)
• They are limited only to actual system requirements (this involved dropping a sentence or two about the installer itself)

All this is intended to keep the Quickstart guide as short as possible, and I also raised #4205 to make sure the guide's abstract explains the scope as well.

[ekohl]

Thanks! Now it's way shorter and I really like that.

[maximiliankolb]

style-wise LGTM

[aneta-petrova]

Merged to "master" and cherry-picked:

17fbcad..df3ba87 3.16 -> 3.16