Discourse Needs help resources and documentation


It would be useful if Discourse came with a help section on how to use it, and explanations on how to set it up. We had to find out how to do everything worked by trial and error. Searching through this forum is time consuming and oriented towards developers.

(Michael Downey) #2

Did you find the New User tutorial from @discobot helpful?

(discobot) #3

Hi! To find out what I can do, say @discobot display help.


Yes, it was helpful for more advanced features, but our new users needed even more basic site usage information. I had to make my own help section and tutorial so they could figure out how to navigate and post.


Plus our users (mainly teachers) were not familiar with chatbots and the word ‘discobot’ did not denote ‘Help’ to them…

(Kris) #6

If you wouldn’t mind sharing it, we’d be interested in seeing what kind of guidance your users needed. Are these people who are generally unfamiliar with forums in general, or are there features specific to Discourse that they were struggling with?


They are not familiar with forums and their mental model is more ‘Facebook’ oriented. In the usability testing I preformed a good number struggled with a variety of simple tasks. I will ask permission to share our Help resources…

(Barbara Kerr) #8

I’m in the process of creating similar documentation. I have many older users who are used to listservs and are very tech-challenged post-migration.

(Jay Pfaffman) #9

When I was using Discourse to teach courses in instructional technology, I set up challenges for students (many of whom were in-service teachers) to do. My assumption was not so much that people needed to be shown how to do things as much as they needed to know what was possible. For example, you don’t need to be shown how to customize you profile, you need to know that you have a profile and that you can customize it.

Similarly, just telling people to get the badges lets them know what things are possible, and it’s not that hard to go and do it, and you get a badge!

(Jeff Atwood) #10

Are these users unfamiliar with the web in general?

(Christoph) #11

Hm, interesting. My assumption tended to be the exact opposite: non-technophile people don’t care about all the great features and therefore won’t read your instructions (or do the discobot tutorial for that matter) unless it promises to solve the exact problem they have right now).

Maybe it helped that you as the teacher were in the position to actually do stuff, whether they want to or not. Or, perhaps even more importantly, that you met them in class and told them in person: if you do this quest, you won’t regret it.

(Jay Pfaffman) #12

Or maybe my students were coerced to do what I told them for a grade. I suspect you’re right.


Hi Jeff, Our users are comprised entirely of teachers, their skills on the web vary widely. Some users had no problems using Discourse while others found it confusing.


Hi Kris,

Here is a summary of what the users needed help understanding how to do:

  1. How to Reply to a topic (there seemed to be confusion over the inline reply vs the main reply and why their post was not on top. There was also confusion over why a post appears under the inline replay and at the bottom on the feed. Users described posting as ‘all over the place’…)
  2. How to add a new Topic
  3. How to Log Out (it was not a separate menu item)
  4. How to Upload a Picture (upload icon unclear it relates to images)
  5. Why there were both green and blue notifications

It might be helpful if Posts were more delineated…

I think some very basic user guidance might be helpful. Once they got the hang of it they seemed to like using the application. Some users would not interact with it because it appeared to require too much interaction cost.

(Jeff Atwood) #15

Fantastic, this is exactly the kind of feedback I was looking for. @erlend_sh perhaps we could make short videos on these topics, or pay someone to do so at a high level of production quality?

(Barbara Kerr) #16

I’d like to add at least one help topic to consider:

  • How to send a private message [PM] vs Reply (which goes to all).

I have cobbled together a not-so attractive document (with screenshots) after a few accidents where the whole member list received what one member thought was a single reply to an individual. A video would be helpful. Or at least a library of standardized, well-described, help topics for new users.

(Jeff Atwood) #17

Are your comments mailing list specific, though? Because that’s a very different use case than web browser participation.


I’ve had users contact me with the same concerns:

  • How do I send a PM?
  • Will my message be posted in the forum or privately?

A few have replied to a post they received by email thinking they were doing it privately.

(Barbara Kerr) #19

I am thinking about both, mailing list and browser. The majority of my members have been migrated from a listserv, so they are used to that functionality. Training them to the web site/browser will take some doing. Still, IMHO, it’s not obvious to any new user how to reply to an individual (i.e. MESSAGE) vs replying to the group, no matter the environment. I don’t think Discobot covers it, but that would not a be complete solution since not all of my people opt to participate in the bot tutorial.

That leaves me with cooking up a bunch of “How to” postings. Being lazy (busy) I’d love to have a library of this info to copy/cross-post so that I don’t have to go to the effort of creating it when - probably - others have written something similar for their Discourse sites.

(Jay Pfaffman) #20

Discourse does not reveal users’ email addresses. Unless mailing list mode reveals them or there is something that I’m missing, there is no way to reply-only-to-sender when replying to a non-PM message via email.

This is counter to how email lists work. As usual, there is a trade-off between increased privacy/security and convenience.