Simplify flavor+version navigation paths

[aneta-petrova]

What changes are you introducing?

This is an attempt to simplify the way users can navigate docs.theforeman.org, namely by:

• Removing the current flavor dropdowns from the top menu bar and replacing them with new version pages, each with collapsible lists
• Removing a few links from the main landing page and adding them to the top menu bar instead

Wherever possible, I'm making use of native AsciiDoc features (hence the use of collapsibles) so that the result is easy to understand and modify by any writer familiar with AsciiDoc.

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

I'm trying to address these issues that currently affect docs.theforeman.org:

• Users can't use full-text search to find the guide they need
• Navigating between the flavors and versions is not straightforward enough

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

The idea is to split the navigation path into two steps: First choose the version, then choose the flavor. This is to give users one choice at a time. With the existing navigation, they can choose either the version or the flavor at the beginning of their navigation path, which is confusing.

Checklists

• [ ] I am okay with my commits getting squashed when you merge this PR.
• [x] I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• [ ] Foreman 3.13/Katello 4.15 (EL9 only)
• [ ] Foreman 3.12/Katello 4.14 (Satellite 6.16)
• [ ] Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9)
• [ ] Foreman 3.10/Katello 4.12
• [ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• [ ] Foreman 3.8/Katello 4.10
• [ ] Foreman 3.7/Katello 4.9 (Satellite 6.14)
• We do not accept PRs for Foreman older than 3.7.

[github-actions[bot]]

The PR preview for 3e9aa55a244267a9cd1bff77a827c44d798cbe04 is available at theforeman-foreman-documentation-preview-pr-3657.surge.sh

No diff compared to the current base

show diff

[aneta-petrova]

Notes from today's triage: Generally, ack, this is seen as an improvement over the current website navigation.

Current blocker: Not all version files (the ones linked from the version dropdown) are currently populated with a list of guides. I will add this.

Also, I want to experiment with different options for how to present the collapsible lists, to find out if it's possible to keep the Katello list uncollapsed by default.

[aneta-petrova]

In #1204 I played around with having those landing pages within the branches themselves. It may be worth investigating that again. I think long term it can easy maintenance.

That is what worries me most about the solution I propose: That maintaining a list of guide links manually for each version is heavy maintenance. But then again, I try to keep in mind that we also need a solution that is easy to understand and update by any writer.

[ekohl]

My idea comes to have something like guides/index.adoc in every branch and then somehow gather all of those when building the website. That way the index lives very close to the actual guides. For me it's hard to estimate if that would be easy to understand by any writer, but I think it would because (as you also said) it's using tooling writers are already familiar and in a directory you already work in.

To be clear: I don't mean we need to block your effort on it and it can be done as a follow up.

[aneta-petrova]

Also, I want to experiment with different options for how to present the collapsible lists, to find out if it's possible to keep the Katello list uncollapsed by default.

@maximiliankolb To follow up on this, these are two things I tried:

I have to say that I still prefer the current, collapsed by default. To me, it still seems like the simplest and cleanest solution, and I don't think the one extra click is too much of an issue:

I'm going to proceed with the collapsed-by-default approach and, as discussed at today's triage, we can always improve later :)

[ekohl]

Something I thought about was taking more of the tabs approach, but no idea if it's actually feasible/usable.

Basically have a header that's Foreman $version and then 3 big tabs:

• Foreman on EL
• Foreman on Debian/Ubuntu
• Katello

Depending on the tab, you see the list of guides. You can also consider adding logos to the tabs for additional visibility. The asciidoc tab plugin can use cookies to store the user's preference so if you navigate to other versions it should remember what the user has.

[aneta-petrova]

I couldn't get tabs to work: I tried on my own and then also when I checked out your web branch. I never got the tabs, always just the example block. That's when I thought of collapsible lists as an acceptable alternative.

[aneta-petrova]

I'd say this is now ready for review. Instructions for testing the website locally are in /web/README.md

This is what it looks like:

• The main page. Note the missing flavor dropdowns, they are not necessary anymore thanks to the collapsibles on individual version pages (see later screenshots):

• Collapsed list of guides for one of the versions:

• The same page, with one list expanded:

• The version dropdown remains unchanged:

[aneta-petrova]

I'd appreciate a review especially from @maximiliankolb and @ekohl. Can you please take a look when you have a moment?

[maximiliankolb]

I'd say this is now ready for review. Instructions for testing the website locally are in /web/README.md

I could not get this to fully work locally, so thanks for the screenshots.

My feedback

• "Show all guides" > reword to "Documentation for Foreman Foreman Version/Katello Katello Version on OS" or similar. Technically, "Release notes" are not a guide. I have no strong opinion.
• "Deployment and installation": > "Deploying Foreman/Katello"
• "Server administration": > "Administrating Foreman/Katello (I think "server" is kinda unfortunate here because readers might confuse this with "I want to manage my RHEL 9 server" which is a client in the context of F/K.)
• "Host administration": > "Administrating hosts"
• I see "managing content" in the section about Hosts, not about F/K maintenance/installation.
• ACD is also part of Hosts
• In web/releases/nightly.adoc, we could use attributes for titles if we set the build flavour for every collapsible.

Overall, I like it a lot!

[aneta-petrova]

* "Show all guides" > reword to "Documentation for Foreman _Foreman Version_/Katello _Katello Version_ on _OS_" or similar. Technically, "Release notes" are not a guide. I have no strong opinion.

I think "Documentation for [...]" would be way too many words for such a small (albeit important) UI element. An alternative would be "Show all documentation". But then again, in-app content like web UI descriptions or Hammer --help pages are also documentation so that would also not be entirely precise :upside_down_face: Additionally, I must say I do consider Release notes a guide :shrug:

For now no change and I'm sticking to "Show all guides". I'm willing to reconsider if there are further objections.

* "Deployment and installation": > "Deploying Foreman/Katello"

Applied.

* "Server administration": > "Administrating Foreman/Katello (I think "server" is kinda unfortunate here because readers might confuse this with "I want to manage my RHEL 9 server" which is a _client_ in the context of F/K.)

How about "Administering Foreman server" to make sure users don't confuse this with any other server? This is because I like the distinction between "server" and "hosts". Therefore, I used "Administering F server", let me know if you think it doesn't work.

* "Host administration": > "Administrating hosts"

Applied.

* I see "managing content" in the section about Hosts, not about F/K maintenance/installation.

It's in "Administering Foreman" now.

* ACD is also part of Hosts

This is in "Deploying" now.

* In `web/releases/nightly.adoc`, we could use attributes for titles _if_ we set the build flavour for every collapsible.

A good idea (and I do miss the option to use attributes for titles) but then as part of the release process, someone would have to replace those attributes with hard-coded title names, right? I don't think it's a good idea to add that step to the process. So no change.

Overall, I like it a lot!

Yay!

[aneta-petrova]

An unresolved concern that I have is whether I can now delete all *.json files under /web/releases :shrug: Was their sole purpose to build the old navigation menu or are they needed for something else too?

[maximiliankolb]

I think "Documentation for [...]" would be way too many words for such a small (albeit important) UI element. An alternative would be "Show all documentation". But then again, in-app content like web UI descriptions or Hammer --help pages are also documentation so that would also not be entirely precise 🙃 Additionally, I must say I do consider Release notes a guide 🤷

Maybe "Show all documentation" or "Show documentation"? Either way, I am also cool with "guides".

[aneta-petrova]

Maybe "Show all documentation" or "Show documentation"? Either way, I am also cool with "guides".

"Show documentation" is something I can very easily live with :) Thanks, applied.

[aneta-petrova]

One thing I'm not sure about is the additional clicks.

There is more clicking, true. What I was going for was more clicks, but each of them a mindless choice (https://www.goodreads.com/quotes/755485-it-doesn-t-matter-how-many-times-i-have-to-click) because that's my current issue with the usability side of the navigation: you may need very few clicks but as a new user, you have to think hard which click is the one that you need.

I get, however, that for users who already know how to navigate, this is not exactly a change for the better. I would still argue that an interface that tries to pack too many things into it to avoid extra clicks shouldn't be the preferred choice. I don't know the history of the website but I can imagine the current navigation worked quite well for versions 3.7 and earlier (https://docs.theforeman.org/release/3.7/) where there was only one flavor. Version 3.8 adds two additional flavors and that's when the website IMO starts to try to accommodate too many things at once.

* Remember the same version number

[...] Perhaps a thought is to at least separate the current version from all versions. That way you end up in the top bar with:

* About Foreman

* Version x.y

* All versions

Current version ("Version x.y") stays selected in the version dropdown at all times so you don't need to remember it. Which gives you easy access to your preferred version and you don't need a separate "Version x.y" item in the top bar. Or am I missing something and you meant something else?

It would be even better if we also have flavor specific pages. Effectively you could have these URLs:

* `/release/$release` for all 3 flavors

* `/release/$release/foreman-deb` for just the Foreman on Debian guides

* `/release/$release/foreman-deb` for just the Foreman on EL guides

* `/release/$release/katello` for just the Katello guides

Then in the top navigation you would have some Javascript to figure out what best to link to.

I'm afraid that "have some Javascript" is out of my skill zone ;) You have good ideas on how to improve my attempt but I'm afraid I must stay limited to more or less what's already included in this PR.

[ekohl]

Current version ("Version x.y") stays selected in the version dropdown at all times so you don't need to remember it. Which gives you easy access to your preferred version and you don't need a separate "Version x.y" item in the top bar. Or am I missing something and you meant something else?

My idea of making it fixed in the same place is that you then can mindlessly click in the same place instead of having to find the right version in a drop down

[aneta-petrova]

I'd like to avoid this PR going stale yet again so I'll summarize the current status and then will ask for a clear path forward.

• In February, I demoed the new navigation proposal in https://community.theforeman.org/t/documentation-team-meeting-2025-02-13/42198. We tested the new navigation paths and because feedback was positive, I continued working on this.
• In this PR, @maximiliankolb shared feedback and confirmed his support of this change: https://github.com/theforeman/foreman-documentation/pull/3657#issuecomment-2846582506
• In this PR, @ekohl expressed concern over the impact on navigation from the user perpsective (for example, additional clicks) and proposed further improvements, which I, as an author of this PR, am unable to implement (like adding a new item to top bar navigation that would always display the current version).
• There is a follow-up PR ready (currently draft, https://github.com/theforeman/foreman-documentation/pull/3670), that uses the extra space freed up by this PR in the top menu bar to add useful links there.

My question is this: Is there still agreement on whether this set of PRs is worth pursuing? If yes, I'd appreciate a clear approval. If not, then no hard feelings because I've learned a lot while working on this and I'd just go on to find something else to learn about :upside_down_face:

[aneta-petrova]

https://theforeman.org/handbook.html#Codereviews mentions a label that I really like: Reached an impasse :) We don't actually have it in this repo but if we did, I would totally use it here :) because I really feel like I can't move forward if I don't get further opinions.

[maximiliankolb]

@aneta-petrova What do you think about demoing this (again)? Either at the Foreman Community Demo or at the monthly docs triage meeting. We could invite others to give feedback. If there is no further feedback, we will probably have to do some kind of vote to reach a conclusion.

I am cool merging this or not, but I am not okay with letting it just sit there.

[ekohl]

@aneta-petrova I should have mentioned that we're currently in the middle of branching (https://community.theforeman.org/t/foreman-3-15-branching-process/43138) and I'd like to get that wrapped up first. Especially since you'd touch those files here.

[aneta-petrova]

@aneta-petrova What do you think about demoing this (again)? Either at the Foreman Community Demo or at the monthly docs triage meeting.

I'm not sure about doing another demo. A bolder move would be to merge (if we resolve the conversation on this PR! I wouldn't agree with merging without addressing the conversation here), announce the change, invite others to test it... and then just revert if there are significant objections. The reason is that it would be good to let users try the change for themselves: a demo can't do that and we don't have any kind of test environment, but reverting should always be easy.

@aneta-petrova I should have mentioned that we're currently in the middle of branching (https://community.theforeman.org/t/foreman-3-15-branching-process/43138) and I'd like to get that wrapped up first. Especially since you'd touch those files here.

Sure! That said, I'd like to reach a resolution before the next branching :)

[ekohl]

https://github.com/theforeman/foreman-documentation/pull/3915 implements a compromise.

[aneta-petrova]

Closing in favor of https://github.com/theforeman/foreman-documentation/pull/3915. Thanks @ekohl!