# Include more hints throughout Discourse that link to relevant Docs on Meta
**URL:** https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749
**Category:** UX
**Created:** [May 13, 2024, 12:45pm UTC](https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749 "2024-05-13T12:45:49Z")
**Posts on this page:** 5
**Page:** 1
### Author:  [@traceymoko](https://meta.discourse.org/u/traceymoko)
#### Post date: [May 13, 2024, 12:45pm UTC](https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749/1 "2024-05-13T12:45:49Z")
## Context
Discourse team have mentioned in a few places that they’re seeking to improve the admin experience.
> [@The Evil Bouncy Castle of Settings and Customize](https://meta.discourse.org/t/the-evil-bouncy-castle-of-settings-and-customize/296971):
>
> Let me tell you a story… It was about a year ago, and I was in the process of setting up my very first Discourse forum, finally migrating my phpBB database from 2007 towards something more appropriate to the current decade, thanks to @awesomerobot’s recommendation. The sysadmin just handed over the keys after having done the first half of the wizard (before it tells you to “jump in!”) and now it was my turn to actually set it up for good. I went to the admin panel and opened the settings. The f…
> [@The Evil Bouncy Castle of Settings and Customize](https://meta.discourse.org/t/the-evil-bouncy-castle-of-settings-and-customize/296971/2):
>
> > [@The Evil Bouncy Castle of Settings and Customize](https://meta.discourse.org/t/the-evil-bouncy-castle-of-settings-and-customize/296971/1):
> >
> > Rather, it likely requires a complete reshuffling of both the admin onboarding and information architecture.
>
> You’ll be pleased to hear that this is currently under active development. We’re aware of how complicated Discourse can feel under the hood and have product managers focusing on incremental ways to make it easier.
> [@Why isn't Discourse more frequently recommended as a "community platform"?](https://meta.discourse.org/t/why-isnt-discourse-more-frequently-recommended-as-a-community-platform/221040/105):
>
> We have our work cut out for us, but we are putting a fair bit of focus on these problems. In the last release, we put some effort into the site setup experience in particular. For [this coming release](https://meta.discourse.org/t/discourse-version-3-2/278584) we have focus areas on improvements to the admin experience more generally, as well as on the extensibility of the platform.
## Problem
There are a lot of settings in Discourse and there is a lot of documentation. But you’re unlikely to find the right documentation at the right moment.
## Feature
There could be a lot more places in Discourse settings and menus where the corresponding documentation in [https://meta.discourse.org/docs](https://meta.discourse.org/docs) is linked.
For example, there is the [Understanding Discourse Trust Levels](https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/) blog post which is linked in Discourse installs.
But there are a lot more which aren’t.
For example, there is a how to on deleting a category.
> [@Deleting a category](https://meta.discourse.org/t/delete-a-category/107854):
>
> bookmark This guide explains how to delete a category in Discourse, including the necessary steps to move or delete topics within the category and handle special cases like the “Uncategorized” category. person_raising_hand Required user level: Administrator (or Moderator if moderators\_manage\_categories is enabled) Deleting a category in Discourse involves two main steps: Moving or deleting all topics within the category Deleting the empty category This guide will walk you through both…
It seems to be that this would be relevant/handy to include in the modal where you can see the button for deleting categories.
It could be a link, but it doesn’t have to just be a link for each case – it could be a question mark button that links to the doc, or it could be “Read more…” etc.
The Discourse team could browse through the docs, starting with the major ones, and figure out where in the software would be most relevant place to link to that doc.
(Aka “just in time”)
> **[The “Just In Time” Theory of User Behavior](https://blog.codinghorror.com/the-just-in-time-theory/)**
>
> I’ve long believed that the design of your software has a profound impact on how users behave within your software. But there are two sides to this story:
>
> \* Encouraging the “right” things by making those things intentionally easy to do.
> \*...
## Other software examples
Ghost (an open source blogging software) has a couple of places where their docs are linked to, right when you need it.
E.g. This Learn More button links to the relevant doc:
> **[Creating discount and trial offers](https://ghost.org/help/offers/)**
>
> The offers system in Ghost allows you to convert more paid customers by offering shareable discounts to your audience, as well as offering free trials to your premium tiers.
>
> The offers area can be accessed from Settings → Growth → Offers when you...
Same with here:
> **[Post analytics](https://ghost.org/help/post-analytics/)**
>
> Post analytics in Ghost admin gives you easy access to track your audience’s engagement with the content you publish, letting you see what’s resonating (and what’s not) with your readers.
>
> To help you get the most out of post analytics, here’s an...
Wasn’t sure if this fits into #Contribute > Feature or #Contribute > UX, feel free to move it.
---
### Author:  [@LWinterberg](https://meta.discourse.org/u/LWinterberg)
#### Post date: [May 13, 2024, 7:23pm UTC](https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749/3 "2024-05-13T19:23:31Z")
I’ll have to disagree slightly with that. There are different scopes of help content you can make. If we go by the [Diátaxis model](https://diataxis.fr/), it’s tutorials, how-to guides, references and explanations.
Tutorials probably have a place to be linked in the app itself, such that if you go in on a page with the intent “I want to learn how this works”, you can learn it, even if the page isn’t self-explanatory. Perhaps even a tutorial center which essentially lets you complete a course on the software if you wish.
The other 3 categories I take some issue with.
If I go to the category settings page, there might be 20 different things I’d want to do. Putting a how-to guide there would result in a list I’d have to search - and because I have an expectation that what I’m out for won’t necessarily have a dedicated how-to article, I’ll probably type that question into Google instead of searching through the list.
Off-site references are a bane I have to deal with daily. We have a “reference manual” which will tell you what each slider and button does, down to:
> **Cancel button** : Closes the dialog without applying changes
> **OK button** : Closes the dialog, applying the changes
Using this reference means you have to scroll past _a lot_ of technical stuff before you get to your section, when what you really needed is a tooltip which rephrases an option in a few more words.
If I try to delete a category, the current behavior is _almost_ desirable. I see the button, usually greyed out but with a questionmark, and if I click it, it says:
> Can’t delete this category because it has sub-categories.
or:
> Can’t delete this category because it has 25852 topics. Oldest topic is…
The behavior is good, I know what’s wrong and what my next step is - delete a bunch of posts and subcategories. It would not be improved by linking to the “delete a category” how-to guide instead.
Of course, it still is a band-aid fix to the real problem: **Why doesn’t it let me delete a category with posts in it?** I can delete folders with subfolders and files on my system, why can’t I delete categories with subcategories and posts? If it didn’t have these weird restrictions, there wouldn’t be a need for a how-to guide in the app to begin with.
And lastly, explanations - that is what the “understanding trust levels” blogpost is. When I first encountered it, it was pretty confusing - “is a random blogpost from 6 years ago really the best you have as documentation?” - and it links out to a [reference](https://meta.discourse.org/t/trust-level-permissions-table-inc-moderator-roles/224824?ref=blog.discourse.org) article which lists out all the things in a table, which was more in line with what I expected (though not sorted in the way I expected). Explanations do not help me figure out a task directly, so putting them in a place where a task would be completed doesn’t work too well.
* * *
I think that ultimately, while documentation is important in a few places (eg onboarding, or in instances where design fails), it really is the design which should be the primary focus. Reading or watching a video in which someone explains the website to you rarely is the desired experience.
---
### Author:  [@traceymoko](https://meta.discourse.org/u/traceymoko)
#### Post date: [May 14, 2024, 2:10am UTC](https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749/4 "2024-05-14T02:10:59Z")
> [@LWinterberg](#):
>
> I think that ultimately, while documentation is important in a few places (eg onboarding, or in instances where design fails), it really is the design which should be the primary focus.
Yeah as a past game design student, I wholeheartedly agree with you there. (I remember you’re designer for Audacity. Btw I use Audacity a lot, very grateful for it!)
I think as well that the whole experience could be rethought from the ground up (starting with thinking: “what would an admin like to do, and how can we best help them do that?” for all use cases) to both have the processes be conveyed much better and also have the processes themselves be as straightforward as possible.
For the example there — of not allowing you to delete a category if there are topics in it — a more graceful way of the software handling that could be like this. When you try to delete a category with topics in it, it could first suggest if you would like to:
- move all the existing topics to another category, or
- put all the existing topics into Uncategorized, or
- delete all topics in the category
and then confirming that you would like to delete the category.
I guess seeing that the Discourse team was going for more incremental changes at this stage:
> [@The Evil Bouncy Castle of Settings and Customize](https://meta.discourse.org/t/the-evil-bouncy-castle-of-settings-and-customize/296971/2):
>
> > [@The Evil Bouncy Castle of Settings and Customize](https://meta.discourse.org/t/the-evil-bouncy-castle-of-settings-and-customize/296971/1):
> >
> > Rather, it likely requires a complete reshuffling of both the admin onboarding and information architecture.
>
> You’ll be pleased to hear that this is currently under active development. We’re aware of how complicated Discourse can feel under the hood and have product managers focusing on incremental ways to make it easier.
I was appealing for a lower hanging fruit – adding some links to the most popular/common/major docs where it would be most relevant.
(I might also make a new topic later on for the feedback/suggestions we have talked about here, on improving the experience for deleting categories.)
---
### Author:  [@hugh](https://meta.discourse.org/u/hugh)
#### Post date: [May 14, 2024, 2:12am UTC](https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749/5 "2024-05-14T02:12:12Z")
> [@traceymoko](#):
>
> There could be a lot more places in Discourse settings and menus where the corresponding documentation in [Documentation - Discourse Meta](https://meta.discourse.org/docs) is linked.
I like this suggestion a lot - thanks for highlighting it, @traceymoko! We’re currently working on improving the general structure and categorisation of our documentation, and I think this kind of feature would be worthwhile to consider as part of that process. I’ll add it to the documentation roadmap as something to explore, and we’ll see how best it could be implemented.
---
### Author:  [@pacharanero](https://meta.discourse.org/u/pacharanero)
#### Post date: [April 19, 2025, 12:48pm UTC](https://meta.discourse.org/t/include-more-hints-throughout-discourse-that-link-to-relevant-docs-on-meta/307749/7 "2025-04-19T12:48:57Z")
Sorry to revive an old topic, and very much aware of the current work that’s happening around Admin search and improving the overall Admin experience. Many times in the last few weeks I’ve been thinking how much I wish that the Name of each Site Setting was a link to the relevant documentation topic on Meta. Over the past few years the Meta documentation has improved vastly, and is now quite comprehensive, organised, and informative.
Example:
In the above example I’d like “Backup location” to link to a Meta topic like [Configure automatic backups for Discourse](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855?silent=true)
Could we gradually approach a stage where each of these Site Setting names would link back to the relevant Meta thread? I can see you might not want to hard-code URLs into Discourse code, but I guess it could be in the Site Texts somehow.
The work of doing all this linking is quite large, but perhaps a crowd-sourced effort across a number of self-hosters would be possible?