Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
asteflova opened this issue Nov 11, 2024 · 2 comments
Open

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

asteflova opened this issue Nov 11, 2024 · 2 comments

Comments

@asteflova
Copy link
Member

asteflova commented Nov 11, 2024

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

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.
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).
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
Copy link
Contributor

  • 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
Copy link
Member

ekohl commented Nov 11, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants