Make upgrade section more visible

[im-konge]

Information about upgrade/downgrade is part of our Deploying and managing documentation section.
However, it's a bit "hidden" in all other content we have in that section.
For new users it can be a bit confusing, so we should maybe add some tile to point into the upgrade part of the Deploying and managing section.

[ppatierno]

add some tile to point into the upgrade part of the Deploying and managing section.

Wdym? We don't have tiles within the Deploying and managing section, we have tiles in the root documentation. I am not sure upgrade deserves a tile itself. It's a day 2 operation and part of managing. If you are referring to the ChatLoopBackOff webinar, I think the user did just wrong that installing a specific version of Strimzi was an upgrade operation (it was a question from a user and totally different from upgrade process). I agree we should highlight the ways to install, but you already opened #502 for that.

[im-konge]

We discussed this offline with @PaulRMellor that there can be tile for the upgrade section in the Documentation page - where we have other tiles like Get Started or Overview. But if you think it doesn't make sense to have something like this, we can just close the issue :)

[ppatierno]

But if you think it doesn't make sense to have something like this, we can just close the issue :)

Absolutely not. It's just my opinion. We have to gather other @strimzi/maintainers opinions and make a decision all together ;-)

[katheris]

I agree that it would be useful if it was easier to find. As a user if I wanted to do an upgrade presumably I would go to the docs and it is a long way down the document. However I don't think adding a new tile is necessarily the right solution. You could argue to add tiles for many other topics, like Connect or Cruise Control or Metrics, so where do you stop. Instead I think we need to see if we can improve the way it can be found. There are 34 top-level items in the Deploying and Managing doc, upgrading and downgrading are items 30 and 31 respectively, and all sub sections are shown.

So I have two questions:

1. Should those sections be higher in the list since after initial deployment they might be some of the most visited items?
2. Can we make the ToC collapsible so when the page loads you only see the top level items? Would that make it easier to find?

[katheris]

As a separate but somewhat related point, the current structure of the Deploying and Managing doc is not great for SEO. If I search for e.g. upgrading Strimzi then it will serve that doc, but then I still have to search to find the part I want. I wonder if we should consider having a paged version of the doc. So when clicking the Deploying and Managing tile I see something that explains or lists the high level topics for me to easily jump to where I want, but then the content is paginated. That way when searching in a search engine I can be linked to a page with less content on it. We could still group some topics, but it might make it easier to navigate.

[PaulRMellor]

We could have a separate upgrading guide (and a separate tile) with the content from chapter 30, 31, 32 but I know there is resistance to more guides. I actually don't think a tile for "upgrading" that links to that section of the guide is a bad idea for a quick win. It doesn't mean you need more tiles for anything else. We could also look at reducing the number on headings in the TOC or other ToC improvements

[katheris]

Triaged on 17/7/25: After discussion we decided we should rename the existing "Deploying and Managing" tile to be "Deploying, Managing and Upgrading". For now we won't create a separate doc or tile for upgrading.

Separately @katheris will raise an issue to remove the 3rd level of the ToC to make it easier for people to scan to ToC.