Make the tshout guide easier to follow

[lhajouji]

Description

Hi team,

I’ve been looking at the Kyverno Troubleshooting Guide, and while it’s really helpful, I feel it could be easier to use. It’s a bit hard to find what yo need quickly because everything is in one long section.

Here are a few ideas that might help:

break it up: It would be great if the guide was split into sections like installation issues, policy problems, performance issues, and specific problems with clusters like EKS or AKS ...

add examples: Some parts, like “Policies are not applied,” could use more examples. Showing the exact commands to run and what the output should look like would make it easier to follow.

add a table of content: A little table at the top with links to the different sections would make it much quicker to jump to the part you need.

more details for common problems: Some areas, like webhooks not working or AdmissionReview payloads not matching, could use more step-by-step instructions.

make solutions simpler: It’d help if each solution started with the symptom, then explained what’s causing it, and finally how to fix it. A short tip on how to avoid the problem would also be great.

I think these small changes would make the guide way more user-friendly, especially for people who are new to Kyverno or troubleshooting Kubernetes.

Thanks for all the great work you’re doing!

Slack discussion

No response

[welcome[bot]]

Thanks for opening your first issue here! Be sure to follow the issue template!

[realshuting]

HI @lhajouji - thanks for the suggestions, and PRs are welcome😃

We could start by adding a table of content for quick navigation and filling out details as follows.

[lhajouji]

Hello @realshuting , since no-one took this, i will gladly work on this , you may assign it to me.

[CortNick]

Hi @realshuting, I see this still has some work to be done on it and I think it might be something that can benefit the community at large. I'm happy to continue work here following the TOC previously added. You can assign it to me for continued work as desired.

[maheshcodes12]

Hi @realshuting, I see this still needs some work. Can I take it up and complete the broken link checks?