Linking to RHEL docs: all doc versions, or perhaps just the latest?

[aneta-petrova]

When referencing RHEL documentation, we list all the relevant RHEL versions. For example:

• https://docs.theforeman.org/nightly/Installing_Server/index-katello.html#Enabling_Connections_from_a_Client_to_Server_foreman

For more information, see [Using and configuring firewalld](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_firewalls_and_packet_filters/using-and-configuring-firewalld_firewall-packet-filters) in Red Hat Enterprise Linux 9 Configuring firewalls and packet filters
or
[Using and configuring firewalld](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html-single/configuring_and_managing_networking/index#using-and-configuring-firewalld_configuring-and-managing-networking) in Red Hat Enterprise Linux 8 Configuring and managing networking.

• https://docs.theforeman.org/nightly/Managing_Content/index-katello.html#Managing_Container_Images_content-management

For information about containers for Red Hat Enterprise Linux Atomic Host 7, see [Getting Started with Containers](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux_atomic_host/7/html/getting_started_with_containers/index) in Red Hat Enterprise Linux Atomic Host 7.

For information about containers for Red Hat Enterprise Linux 8, see [Red Hat Enterprise Linux 8 Building, running, and managing containers](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html-single/building_running_and_managing_containers/index).

For information about containers for Red Hat Enterprise Linux 9, see [Red Hat Enterprise Linux 9 Building, running, and managing containers](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/building_running_and_managing_containers/index).

• (Satellite only): https://docs.theforeman.org/nightly/Managing_Hosts/index-satellite.html#Managing_and_Monitoring_Hosts_Using_Cockpit_managing-hosts

For more information about using the RHEL web console, see the following documents:

    [Managing systems using the RHEL 9 web console](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/managing_systems_using_the_rhel_9_web_console/index)

    [Managing systems using the RHEL 8 web console](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/index)

    [Managing systems using the RHEL 7 web console](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/managing_systems_using_the_rhel_7_web_console/index)

This convention becomes difficult to maintain because RHEL docs get restructured which breaks the links. Getting links to all versions up-to-date again is tedious, not to mention temporary (because we've seen the links break again on a few occasions).

It makes me wonder whether the benefit for users is even significant enough to outweigh the cost of maintaining these links. Would it perhaps be enough to link only to the docs for the latest supported RHEL version instead?

[maximiliankolb]

• For any links that refer to the Foreman Client platforms (EL, SLES, Debian/Ubuntu), I think latest only is fair unless we really need it because there's a big difference between RHEL7-8-9 or Ubuntu 22.04 to Ubuntu 24.04. We could default to "latest only" and deviate on a case-by-case basis.
• For any links that refer to the platform of Foreman/Smart Proxy, I suggest to align it exactly to the list of supported OS. If the difference is miniscule, then I'm also very much OK linking to, for example, "chrony on RHEL9" only. It's not rocket science to read the title of a link such as "Enabling chrony on RHEL 9" and think, "ah, I'm running Foreman on RHEL 8, so I'll just use a search engine".
• If it's a more or less random list of links as part of "Additional resources", then latest greatest should also always be fine.

Conclusion: Latest greatest only, unless we have specific reasons/requests.

[ekohl]

This convention becomes difficult to maintain because RHEL docs get restructured which breaks the links. Getting links to all versions up-to-date again is tedious, not to mention temporary (because we've seen the links break again on a few occasions).

IMHO this is a Red Hat documentation issue. Links should be permanent and if they change, the old links should redirect. Arguably, anchors could change but the examples you provided don't have anchors.