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

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.

5 Likes