Differences between RL8 and RL9

[nazunalika]

Starting with the basic network configuration page here, there is likely other bits of guides/documentation that may not apply to certain Rocky Linux versions or processes have changed. The documentation should likely be evaluated as a result. Right now, there are users who frequently come to the general channel to ask about certain cases (especially the network-scripts being empty on Rocky Linux 9) being confused as some page assumes the configuration is the same on both 8 and 9.

There are a few things that should be considered:

• Should each major version of Rocky Linux be separated (similar to Red Hat's documentation - this would require a large rework and may not be ideal at all) or...
• Should each guide section that may have differences between Rocky Linux versions noted in subsections of certain steps on the guide pages or...
• Should each guide section have a drop down for each relevant Rocky Linux version

One idea could be:

• Going to the desktop section and clicking the drop down
• See Rocky Linux 8 and Rocky Linux 9, and clicking the drop down for my system
• Seeing the guides that apply for that release

Another idea could be having a button or a way to reflect a given release dynamically on a page (this may be a feature that isn't in mkdocs or a plugin). There are some docs pages out there that do this where selecting a version at the top will change commands or portions of the guide to reflect that release.

[sspencerwire]

Starting with the basic network configuration page here, there is likely other bits of guides/documentation that may not apply to certain Rocky Linux versions or processes have changed. The documentation should likely be evaluated as a result. Right now, there are users who frequently come to the general channel to ask about certain cases (especially the network-scripts being empty on Rocky Linux 9) being confused as some page assumes the configuration is the same on both 8 and 9.

There are a few things that should be considered:

• Should each major version of Rocky Linux be separated (similar to Red Hat's documentation - this would require a large rework and may not be ideal at all) or...

At one point, this is where we were headed. I personally didn't like it because, for many documents, there are no changes. That isn't to say that this might not be the right way to approach it.

• Should each guide section that may have differences between Rocky Linux versions noted in subsections of certain steps on the guide pages or...

I've done some of this on some documents where testing on 9.0 revealed a problem.

• Should each guide section have a drop down for each relevant Rocky Linux version

Frankly, I like this one, but I'm not sure if it is supported in material-mkdocs

One idea could be:

• Going to the desktop section and clicking the drop down
• See Rocky Linux 8 and Rocky Linux 9, and clicking the drop down for my system
• Seeing the guides that apply for that release

Another idea could be having a button or a way to reflect a given release dynamically on a page (this may be a feature that isn't in mkdocs or a plugin). There are some docs pages out there that do this where selecting a version at the top will change commands or portions of the guide to reflect that release.

I was working in another way entirely. My idea was to use the "tested with:" meta that exists in many (but probably not all) documents. I was trying to get the interface to display the "tested with:" and the contents. A common version of this is:

"tested with: 8.6, 9.0"

But, even if we got that to work (which I haven't yet-I can get "tested:" to work but not "tested with:" ) it would show up at the bottom of the document with the author and contributors and revision date, and that might not be optimum, because you really want the person to know up-front what version the document works with.

The short answer is that I'm open (and I'm sure @wsoyinka is open) to ideas. Right now we are restricted to mkdocs availability of a feature. Currently "search" is fundamentally broken too.

This is a very real problem though, and you are correct to bring it up to emphasize the issue. Thanks!

[sspencerwire]

@nazunalika @wsoyinka For documents that have separate procedures that must be run for each version of the OS, I've found a way to at least highlight this within the document. It still isn't ideal, but it works. Essentially you create a collapsible admonition (just a collapsible section doesn't work, as it then requires the lines in the collapsible section to be written as HTML rather than markdown). An admonition is normally formatted this way:

!!! note "custom subject if there is one"

The content of the admonition. 

To make the admonition collapsible, you need to start it with three question marks rather than exclamation marks:

??? note "custom subject"

All of the content for the admonition is formatted with 4 additional spaces, which means all of the section for say 8.6 is formatted with those additional spaces. Visually, it is easy to see on the page, plus by doing it this way, the headers are completely preserved and actually show up in the right-hand TOC. 

This seems to be the only way to add a collapsible section, other than re-writing everything in HTML. For any document that either doesn't support 9.0 or has the exact procedure for doing everything (8.6 and 9.0 are exactly the same) we may have to simply add a disclaimer at the top that says so.

Suggestions? Does this satisfy the problem or do I need to keep digging? Let me know what you think.

[sspencerwire]

I should also say that part of the problem is that we use mkdocs-material. I've found examples using straight mkdocs that don't require turning the entire code into HTML to create a collapsible section. You still need the beginning and ending tags such (<details>, <summary>, with end tags for those), but otherwise it seems to honor the markdown within. Not so with mkdocs-material unless you use the collapsible admonition.

[sspencerwire]

One more thing. If either of you wants to see this in action, I can merge the single document revision (where the example came from).

[sspencerwire]

I wanted a live example, so I've merged the document in question: https://docs.rockylinux.org/guides/backup/rsnapshot_backup/

[sspencerwire]

@nazunalika @wsoyinka I found another method for displaying versions within a document that is in many ways cleaner. It does require a small change to the mkdocs.yml file, but the feature already exists in our current version of mkdocs. The feature is called Content Tabs described here. The one downside is that while the right-hand table of contents shows all of the options, clicking on instructions for 9.0, while the tab for 8.6 is selected does not work. The upside is that it is a much cleaner look and feel and is found on other sites as well. I'm adding a screenshot, but the link (included above) shows all of this too.

[sspencerwire]

The mkdocs.yml changes would simply be to add the value "alternate_style: true" to the already included extension "pymdownx_tabbed" which already exists:

  - pymdownx.tabbed:
      alternate_style: true