nextflow
nextflow copied to clipboard
nextflow-io
Refresh troubleshooting docs
This PR aims to refresh the troubleshooting sections in the docs. Text has been revised and new headings have been added for easier navigation.
Deploy Preview for nextflow-docs-staging ready!
| Name | Link |
|---|---|
| Latest commit | aafa33a6433a9e56872f63cdbe68091f3d28ce3a |
| Latest deploy log | https://app.netlify.com/projects/nextflow-docs-staging/deploys/682d5cad496a230008703828 |
| 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 project configuration.
![netlify[bot] avatar](https://avatars.githubusercontent.com/in/13473?v=4 "Published by a pub.dev verified publisher"){kind=small}
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
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?
All of the troubleshooting sections should remain on their respective pages, but you can still have a "troubleshooting" page that links to those sections
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.
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
Fair enough. I'll convert back to draft and move the pages back into relevant sections.