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

[bloomexperiment (Tracey)]

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

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…

@HAWK

@LWinterberg

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.

@mcwumbly

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

Delete a category

At a glance Move or delete all topics Before you can fully delete a category, you must delete or move all of its topics. If you have multiple topics to delete or move, clicking the   Topic list icon near the top of the category’s topic list will allow you to select multiple topics at once. Once you have selected all of the topics you want to delete or move, look for the gear icon button near the top left. Select that, then choose the option to delete/move all of the selected …

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

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

Same with here:

Post analytics

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

[LWinterberg]

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.

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

[bloomexperiment (Tracey)]

@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:

@HAWK

@LWinterberg

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

[hugh (Hugh Lashbrooke)]

@bloomexperiment

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

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.