Move troubleshooting to new docs section

[christopher-hakkaart]

This PR aims to refresh the troubleshooting sections in the docs. Text has been revised and new headings have been added for easier navigation.

[netlify]

✅ Deploy Preview for nextflow-docs-staging ready!

Name	Link
🔨 Latest commit	8cfe891
🔍 Latest deploy log	https://app.netlify.com/sites/nextflow-docs-staging/deploys/67d82658bdcef100088ba1f6
😎 Deploy Preview	https://deploy-preview-5856--nextflow-docs-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[pditommaso]

i'd argue that as a user it's more useful to find the troubleshooting in the same (infra) context. This would not prevent having a central troubleshooting page linking individual sections

[bentsherman]

I agree with Paolo

[christopher-hakkaart]

To clarify, the cache and language server pages are okay under the troubleshooting section, but you would prefer the storage and compute page to be put back on the infrastructure page?

[bentsherman]

All of the troubleshooting sections should remain on their respective pages, but you can still have a "troubleshooting" page that links to those sections

[christopher-hakkaart]

Having a dedicated troubleshooting section in the side navigation makes it obvious where to find help quickly without searching, clicking around, or ending up on the wrong page. It neatly lists topics, making it easier to scan for relevant information.

Including troubleshooting within individual topics buries information deeper in the docs and there is no guarantee users will follow that path. Also, search previews aren’t always helpful, leading to extra clicks and may lead to frustration. Having a separate troubleshooting would help accessibility and will be easier to scale as content grows.

In the PR, small sections in the relevant topics point to the troubleshooting section, which is the flip side of having a page point at the sections rather than the section pointing at the page. I was trying to avoid an "index" page, as this also adds another layer of depth to the information.

It's no problem to move the refreshed content back into the relevant sections, but I wanted to make a case for the troubleshooting section.

[bentsherman]

The problem is that many of these troubleshooting sections don't make as much sense when you pull them out of their proper context. We would need to re-evaluate every troubleshooting "item" to make it work on its own

[christopher-hakkaart]

Fair enough. I'll convert back to draft and move the pages back into relevant sections.

[pditommaso]

Nit, as a user I find much more intuitive YOUR something to understand it's a placeholder that I need to replace

[christopher-hakkaart]

We're slowly moving towards a standardized placeholder across all doc sets. This is capitalized placeholders with underscores and no possessive adjectives. It's meant to make placeholders clearer and easier to scan. When a replacement action is required, we will start adding "Replace with your XXXX" or something similar below the example. I didn't add a replacement instruction here as it's an example of what the error message looks like.