Include more hints throughout Discourse that link to relevant Docs on Meta


Discourse team have mentioned in a few places that they’re seeking to improve the admin experience.


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.


There could be a lot more places in Discourse settings and menus where the corresponding documentation in is linked.

For example, there is the 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.

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”)

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:

Same with here:

Wasn’t sure if this fits into feature or ux, feel free to move it.


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, 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.


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 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.


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:

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.)

I like this suggestion a lot - thanks for highlighting it, @bloomexperiment! 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.

1 Like