Add a Troubleshooting section with common mistakes and pitfalls focusing on making the initial setups run smooth.

[stevepiercy]

@acsr added this as a note on the project board, but not an issue. I converted it to an issue.

When installing a new Plone6 setup without latest experience in the new Plone6 stack that completely changed the approach how Plone is setupo and or deployed, you can win or loose our audience and have serious chances to spoil the way to success.

I give some examples:

1. Missing qualified requirements in detail, matching the current (latest) versions of both Plone (Classic) Backend and Volto.
2. Running the Frontend and missing the styles because of firewall confis not knowing what ports need to be open, forwarded or why a host IP need to be configured during the start of the frontend not only what but also where and how!
3. Exact places (filesystem layout) of the relevant configurations, and or write them as human readable report not only during install to stdout, but show this by opening a report file during first run or point to this a s a log.
4. Matrix of namespace issues during the Deployment Setup following the cookieplone step: Repo Name, Organisation Name, meaning of common errors and how to fix them.

These are just based on my personal odyssee. I had some smooth initial test installs, but recently (since February 2024) I am running into trouble almost every day when I try it. I know without contributions we cannot expect this to be perfect from scratch.

I suggest to

1. Make the "Repository" link in the top icon row of the doc pages exacly point to the related current markdown source file, not just to the root of the repo.
2. Create a single point of truth troubleshooting example startpoint. Better wording suggestions welcome…
3. Try to parse the usual community locations for solutions
4. Feed a RAG based AI search with this to praise Nuclia!
5. Prompt the helpdesk assistant with the context of the raised question * Create a "request for help" link format that takes the context into the system prompt before opening the search input context.
6. Make it easy to link back the solutions to the origins of the request for help in the web (Stackoverflow at https://stackoverflow.com/questions/tagged/plone, https://community.plone.org/ etc.)

[stevepiercy]

@acsr, I found this as a note in the project board, and not an issue, so I converted to an issue for discussion.

I believe that issues were created for all the items you reported. If not, can you provide details and create issues in the appropriate repositories?

As far as suggestions.

1. This is not supported in any Sphinx theme that pulls in submodules. If you want to hack together a Sphinx extension to resolve, be my guest, otherwise this is "won't fix".
2. Troubleshooting of what? In general, troubleshooting should be in the context of the page. It would a heavy maintenance burden to aggregate all those troubleshooting tips into a single point of entry. Again, if this is something you would like to tackle, be my guest.
3. There is a fair amount of cross-pollination between Documentation and Community Forum. If there is something specific that should be added to Documentation, then please let us know.
4. I don't know what is RAG, but we do have plans to implement Nuclia. Ongoing work is in Integrating Nuclia Widget training#792. Help needed!
5. We do not have a help desk assistant. By default, the search is provided by Sphinx, and it is not great. Again, we have plans for that.
6. Permalinks are provided for every section heading in Documentation. Nothing to do here.