The discussion revolves around improving the clarity and accessibility of Discourse settings descriptions. Jonathan5 suggests adding more detailed explanations or links to Meta forum threads for each setting, acknowledging that current descriptions are often too brief to be useful for new users. Moin links to a related topic, prompting Jonathan5 to reflect on the lack of a centralized manual or overview. JammyDodger supports the idea of in-app links to live Meta guides for up-to-date info and use cases, but later agrees withitsbhanusharma that sending users offsite could harm UX. itsbhanusharma argues for concise in-app descriptions and a separate, externally hosted Quick Reference Handbook (QRH), preferably on Meta, to ensure timely updates without the delays of core software deployment. ganncamp proposes grouping detailed descriptions by category instead of per setting. itsbhanusharma reiterates that external documentation is essential for maintainability and accuracy, warning that built-in descriptions would quickly become outdated due to Discourse’s release cycle. The consensus leans toward keeping in-app descriptions short and supplementing them with a well-maintained external resource.
It would be good if there were an additional paragraph and/or link to the forum for settings.
This is more of a generic pipe dream than a specific feature request so I don’t really expect it to be implemented Though maybe the sentences could be a bit more descriptive.
You haven’t added your own comment, but I guess that it would have been that I should have searched before posting and that if I had I would have found that topic and reply
That is an interesting topic, as what @codinghorror says is a good defence to my position, but it doesn’t really answer @ganncamp’s question which was more about the absence of a manual or an overview of settings overall.
I like the idea of there being a link to Meta/a live guide within the admin settings, so you can zip through and find the latest information, and possibly even a few suggested use cases people may not have considered. Not sure what it would look like in practice, but it’s definitely got me thinking.
Yes, I think you’re right. I was idly looking at the settings page thinking about what it could look like, and I think one per setting would be too much. You’d want the best ‘short’ description next to the setting no matter what, and I can’t picture how to put anything extra in that wouldn’t detract from that simplicity.
But a quick reference would be good. Are you thinking inbuilt, or a link to some kind of FAQs set-up here on Meta?
Should 100% be a link to meta (or an external document) which contains one para description of the setting. Any more literature and nobody bothers to actually read it.
We need it on meta or another external site because it is easier for us to manage any discrepancy. If it is built into discourse package, it will be hard to add the most accurate information due to the reason that the process is long between a pull request being written, tested, reviewed, merged then actually being deployment to every customer running different branches. The info could get out dated pretty quickly.
Though maybe the sentences could be a bit more descriptive.