Best Practice: Creating local user guides

You’re install is up, everything is running fine, and users start arriving. All in all, a grand thing.

then the questions start: How do I upload pics? How do I edit a post? How do I use search? How do I add a cool picture like Schmedly has?

Depending on your user base, you may end up herding cats. Even with the Canned Replies Plugin installed, you will find that the same questions come up over and over again, and answering them all begins to feel like knitting fog.

Here is how I did it:

  1. Create a category for “User Guides”, make it read only for normal users.
  2. When a question arises either compose a guide, or answer it in topic, then move the topic into the “User Guides”
  3. Add the “User Guides” category to the “default categories watching” setting**.
  4. Keep referring users to the “User Guides”, they will eventually start helping each other, either by helping to create guides, or by pointing users with questions to the Guides category.

**Note:Changing this setting does not apply retroactively, so you want to change this setting before many users arrive. If you want to make the setting apply retroactively you can do so from the CLI. What you need to do is detailed in This topic.

Here is the User Guides Category on the site I moderate.

These were all written just using the composer and screenshot tools. Many of them started as PMs between a User and I, and once we’d got them complete I just moved the PM to the Guides section.


That’s a question I got a lot, so I used the Admin > Customise > Text Content to change the word “Upload” to “Upload Photo”

This helped massively:

Our “how-to” guides are here:


Chris, I think your Summary page page is slick! How did you generate that?

Ah, thanks :slight_smile:

It’s just a static topic which I manually maintain. I also maintain another “directory topic” for local recommendations, which is hard work for me but it’s a very useful page for members.

It would be so helpful if Discourse had a feature allowing mods and trusted members to curate directory pages without having to manually copy-paste links and edit topics. I think more people would get involved if they had the tools (seems people are reticent to edit my wiki pages for some reason).

If “directory pages” were a first-class feature of Discourse, they could also be listed in the hamburger menu too perhaps. I’m very nervous about hardcoding JavaScript to do this, given APIs change over time.


That would be cool if it could be automated, or even semi automated! Manually maintaining that kind of stuff isn’t so bad if you’ve only one page like that, but it is a bit like maintaining a static site. It would be amazing if there were a “Make a Summary of this category” function, even if all it did was PM you a message which had the summary in alphabetical order. Perhaps if it only harvested topics with a tag like “Summary-Page”?

Building directory pages by harvesting tags is a great idea @JagWaugh!

I suppose what we’re looking for is an alternative to the current individual tag pages. An alternative where:

  • topics are listed alphabetically
  • topics are listed more succinctly (fitting more per page)
  • accessed via hamburger menu > my_directory_page rather than hamburger menu > tags > my_directory_page
  • further categorisation possible within a directory page using sub headings (unsure how this would be managed)

Sorting topics alphabetically has come up a few times. Here is the latest…

I wish we could get there too. Not sure of the tecnical aspects.

1 Like

Sorry if this is a dumb question, but why exactly do you recommend this?

My concern: I would be sending totally unsolicited messages to all users and while some may understand the idea of these “by these by the way, did you know…” emails and be happy to receive them, I think they may well confuse many more users and make them feel out of control (“the forum is sending me stuff I never asked for”)…

1 Like

No such thing as a dumb question.

Our forum is all about Jaguar cars, with a separate category for each model. The first thing that most users who customised their profile did was mute every category except for the one covering their Jaguar. Many then started asking questions about how to do things, and where the help files are.

I haven’t changed or added much to the user guides category in the last few months, but having the category in the default meant that as we went live and I was publishing new material users either saw it because of the default watch, or when they asked “How do I…?” on a model forum, some user who had seen the guides as a result of the default setting could answer “There is a guide about that, published yesterday, see X”.

I didn’t want to get into the game of composing a guide, then creating a topic in each category “New user guide available for “X”, see #user_guides for more info.”