Discourse documentation


(Sarah Hawk) #1

I feel like recently someone told me about a site that has some documentation on using Discourse, but I can’t remember who or where. It wasn’t official documentation from the Discourse guys.

Anyone know what I’m talking about? (or where something like that might be hanging about?)

@erlend_sh @JoeBuhlig @Jay_Pfaffman


Directory of Discourse help topics from many forums
[22 May] What are you working on this week?
Discourse users – what is missing from your Admin dashboard
(remah) #2

There’s a couple of categories on sites mentioned in this topic:

They aren’t comprehensive but the topics obviously depend upon what each community needs:


(remah) #3

Here’s some relatively generic Discourse how-to topics I setup for forum.glasswire.com. I started their How-To category to help them out and learn what I need for a soon to be implemented Discourse install. I’ll be converting entire manuals into linked topics. So any feedback, positive or negative, will be much appreciated:


(Sarah Hawk) #4

Brilliant! Thanks very much.


(Piper_Wilson) #5

This is beautiful. Thanks!


(Jay Pfaffman) #6

There was once a site that attempted to organize the howtos in a cogent manner, but it’s abandoned (or gone).

On my list of Things to Do is to develop a book and/or an online course to help people learn to get up to speed. What I’ve been doing thus far is developing resources like the ones linked below for my clients as they need and ask for them.


(Jay Pfaffman) #7

And on a related note, I’ve been tasked with coming up with a list of “best” Discourse sites and finding some kind of Onboarding/New User guide.

It’s for a community moving from Ning to Discourse.


(Sarah Hawk) #8

What qualifies best?

For Discourse specifically, or general community best practice?


(Jay Pfaffman) #9

Oh, it’s in the eyes of the beholder, I’d imagine.

Well, this particular person is interested in how to get his 25K user Ning group happy with the transition to Discourse.


(remah) #10

Do you mean Discourse’s unofficial learndiscourse.org that is now the official https://meta.discourse.org/c/howto:
https://meta.discourse.org/t/unofficial-community-docs-learndiscourse-org/31931?u=remah

A directory of useful help references?

Would it be worthwhile having a wiki post something like the following which we can add to either here or at meta.discourse.org?

Discourse automation

Blog post

Single post/page

Single post/page as table of contents

Single topic of posts

Discourse category of topics:

Edit: I’m gradually building a catalogue of help pages in this post which is now a wiki post so you can add any you find:

  1. :white_check_mark: Add links to this post as I visit all the publicised English-language sites I can find.
    There’s a list which incidentally has good examples of emoji+text buttons. I’ve completed the topic directory list plus the other 281 posts.
    Now working my way through the Discourse hosted list - up to Education.

  2. Create a new help directory topic here to only include the most useful links organised by heading (e.g. Post) and subheading (e.g. Add Post, Delete Post, …).

  3. Start to create a complete generic Discourse help guide/manual by adding missing topics.


(Piper_Wilson) #11

WOW! Thank you for all the work you’re putting into this. It’s amazing.


(Jay Pfaffman) #12

It turns out that the good folks at discourse.org maintain a list of customers. That seems like a pretty good list of “best” sites. :slight_smile:


(Sarah Hawk) #13

It’s interesting to note that almost all the gaming examples use the dark theme, and everyone else (bar one) uses the light theme.


(Jay Pfaffman) #14

They always play with the lights turned out. :slight_smile:

FWIW all of my windows, except my web browser, have dark backgrounds. At one time, I think it was significantly easier to read light text on a dark background. I’m less convinced that it’s the case today, but most of my work is done in what my wife calls “black boxes.”


(Sarah Hawk) #15

I write code on a black background in Atom, but everything else I do is on white. I find the black Discourse theme a bit depressing.


(Jay Pfaffman) #16

For reasons I can’t explain, I prefer white/light backgrounds on web pages.

On the rare occasions I use a word processor (I generally write text in Markdown, Org, or LaTeX in Emacs, the One True Editor) I have a white background, because WYSIAYG (what you see is all you get), I guess.


(Sarah Hawk) #17

Dark text on a light background is best for readability, but for coding a dark background is preferable to prevent eyestrain over long hours.


(Sarah Hawk) #18

In a crazy inception moment I was just searching for TL explanations and found this.

A Discourse cheat sheet and an explanation of trust levels that I wrote myself in a former life an forgot about!


(remah) #19

In a wiki post above, I’ve completed a list of the relatively-generic help (documentation) topics on the Discourse sites publicised at discourse.org.

Scanning a couple of hundred Discourse sites was an interesting experience. It is easy to identify the sites I’d like to join and the better admins who can set the tone for their forum.

Apart from a few topics, the list doesn’t include any replies buried in responses to help requests. A few links note something unusual on a site. Several links are for optional plug-ins.

I’m surprised that I only found about 175 topics - an average of about one per site. On most sites, almost all the help is buried in replies to requests for assistance and this seems to be much the same even on sites with good help topics.

It is also common to find help requests that could have been solved by a simple search. Sometimes a help request duplicates an earlier request that is still visible on the first page of Latest.

  • Do users not read the Latest topic list or the topics visible against each category in the Categories view?
  • Do users not use search?
  • Do users post a new topic before doing anything else? If so, then that is evidence that Discourse works in reducing the barriers to posting a new topic.
  • Is the Discourse default sufficient for most new users? I noticed that many forums don’t even have the default introductory posts, e.g. removing or not editing category descriptions.

(Robert McIntosh) #20

I promised I would return and leave a link once my site was ‘public’ so here it is. I may be re-creating the wheel with these topics, but I find it useful to try and outline the key issues in language my audience will hopefully understand, and by doing the research, working out how easy it is to do for them (not my usual work-arounds)

Still WIP

Hope it helps others: