Discourse documentation

(Jens Maier) #18

Out of curiousity, what particular piece of info took so long to locate?

(Jeff Atwood) #19

I agree with @elberet it would be good to drill into specifics of what you were looking for and how to improve that. Fun size units of work.

In general our docs are here:

So you or anyone can submit pull requests any time.

(Ron Shannon) #20

@elberet - There were several things I wish I had known or understood, not one. At most stages, I looked here. In candid hindsight, some [most?] of my problems were the result of not even knowing what to ask. A lot of “locate the info” problems were of that variety. A couple of those I luckily stumbled across, or so it seemed to me, as a result of apparent topic drift. Some were undoubtedly Docker issues, some Rails issues – but those are bridges people do have to cross. I’d like it to be easier for them, if possible. I stuck with it, and now have a running instance and am blown away by the design & functionality. My concern is with those who don’t stick with it because, right or wrong, they can’t find a traditionally organized set of documentation, a wiki, whatever – because that’s the way they learn. One doesn’t read here very long before seeing there are many who would like that.

I started to write an example to answer your specific question, but realized that to understand how I got to where I got hung up, and then how and why I didn’t know what to ask, etc., required more context to explain, more sequencing than anybody here would (should) want to read. I don’t mean to duck specifics of the saga, nor my own clueless mistakes here and there. of which there were plenty. (If you really want to know more of that, please PM me and I’ll give you a phone [etc.] number and would be willing to talk about it in more detail with you.)

That said, I’ll offer one item I just stumbled across in another topic, after getting my instance up and running. I assumed/believed/thought ./launcher rebuild app would effect a complete rebuild, and it doesn’t. [The database remains.] If I’d known what I didn’t know, I might have discovered what it wasn’t doing earlier – or maybe not. As you may be able to imagine, that could lead to a significant time sink. At least I take solace in knowing I wasn’t the only one who went astray there while trying to troubleshoot more mundane issues. I got around that by blowing up everything and starting over. Something I’d done wrong before I must have done right the next time.

There are other reasons not to get into long winded specifics here. At least two things are likely to happen, neither good. First, some will say well, that’s not a Discourse problem, that’s a ___ problem, etc. But for better or worse, a lot of people who really want to get hands on with Discourse have to get it running first. I don’t want to debate whether something should be here [meta] in some form or not. I’d just like to give a hand to others, in a form they’re familiar with, if I can.

Second, much as I would try, it might be challenging to go through my saga without sounding critical. “I needed this, didn’t know I needed that, it wasn’t clear enough to me, what I found wasn’t current [enough], etc.” I don’t want to sound negative. much less be negative. That’s not the point. The point of my question was an attempt to find a way add value if I can, in a form that, reading here, it’s obvious many people want, while my own confusions are still fresh.

(Ron Shannon) #21

@codinghorror - I went to the home page here, and put the git docs URL you mentioned above in the search box. Perhaps I did something wrong, even there, but I got no hits. So it’s nice to know. Perhaps if I’d found those, something that I didn’t find before would have helped. I don’t know. I’ll check them out. Even a search for “docs” doesn’t bring that URL up (but there are numerous requests for trad docs) until, well down the list, comes this topic. Maybe indexing takes awhile, or something.

To respond to your request for fun size bits, I will try to reconstruct the process I went through, and all the places I got stuck, scratched my head, and couldn’t, for the life of me, find an answer to what I thought my question was here on meta. It will take me awhile. Really would rather not. I’m afraid you’ll point out where I should have found something. That’s not going to be helpful to the people I’m concerned about, who may also fail to search the right terms as I may have, but whom I think really should get to know this great thing you’ve built but, for whatever reasons, can’t get there. That’s all.

I’m interested in helping people who don’t know what a pull request is.

I guess the answer to my question is that there is not a project, etc., for any kind of traditional documentation, wiki, etc. Having poked around some more, it seems like that is even… discouraged? I hope not. That’s all I asked. I realize you believe in a different approach, which is fine, I guess. Given the quality of your stuff so far, I wouldn’t be surprised if you get there some day, or close. I hope you are successful in reaching those people who are eager to check this out, and would benefit from all your hard work. I have no stats, of course, but right or wrong, good or bad, I’m afraid many walk away.

I’m done.

(Jeff Atwood) #22

Well, I would say the documentation is us talking, here, like we are now. The discussion is the goal of the project, and its purpose. To the extent that we are successful in communicating, right here, right now, Discourse is doing what it set out to do.

It’s also true that, unlike setting up a blog, setting up a single Discourse community serves hundreds, thousands, even potentially millions of people with one instance. So the setup and admin process is somewhat less urgent than the overall usability of the conversations. The needs of the many vs. the needs of the few.

(That said, we get very few complaints about anything in Discourse being particularly hard to understand or use from our paying customers – and as you might imagine we listen with a keen interest to their feedback.)

I am sure we will continue to improve and refine setup, which is currently at 30 minutes. And for those that need something easier still, there is paid monthly hosting or our $99 one time install plan.

(Kane York) #23

Data point: Someone saw a discussion and wanted to know more. There’s nowhere to point them to, though.


(Sam Saffron) #24

That was triggered by a feature we very much want to re-write and perhaps the most confusing site setting we have.

(Kane York) #25

TopicView rewrite 2015!

(Jeff Atwood) #26

In other words, the best reaction to “this is confusing, where are the docs” is to rewrite the feature to make it less confusing – not to write a bunch of documentation.

(Mitchell L Model) #27

Pulled it. How do i assemble the documentation into something I can read (HTML or PDF, presumably) and is any of the stuff in the various folders relevant to someone who just wants to read the documentation?

(Christopher Semmler) #28

This is exactly where my problem begins. We use Discourse in production in our company and users tend not to read the message since they are used to receive (useless) initial sign up notifications from other software. Average Joe is overwhelmed by a new interface he has to learn how to deal with. Once he clicks the notification away, this message is “gone forever” - not in the UX sense but he just doesn’t remember. You can imagine how often I personally have to point users to

  • click on your avatar
  • now click on the envelope
  • NO! dont click there! The envelope icon! Gosh.
  • OK, now do you should see the Messages tab highlighted in red. Correct, the one right in the centre of the screen.
  • Look, this reads “Welcome to Discourse instance!”
  • I KNOW IT IS NOT IN GERMAN, please just read it for now …

Two months later this very user has no clue where to find this information since he expects this to be a topic. Reiterate cycle. Thus I ended up creating a sticky topic which describes the procedure mentioned above. Including images.

In a perfect world every user is capable of finding this info, but in a real world setting users just don’t get it. I don’t blame them since they have to deal with many interfaces and learn something new everyday. Especially concerning users at the age of 45+ this is a real problem.

We also started writing an internal “how to use Discourse” guide since the lack of documentation affects the info management policy of our company. In our workflow we use different tools and as users (not all of them) don’t comprehend how to properly use Discourse, they create a mess in the workflow itself, requiring constant support and thus wasting resources. In an ideal world we are putting effort into actually working on a project rather than discussing the toolset for working on a project.

Next, the user guide in the initial message is not covering all of the functionality.
Example: It took me ages to find out how and when Discourse hijacks the Ctrl+F functionality. It drove me nuts not being able to invoke Discourse’s own logic until I finally found the info on meta.discourse.org.
Example 2: The shortcut key reference is not mentioned in the initial message either. I am well aware that it is totally accessible through the menu but again - in a perfect world …

For admins or site administrators the situation is even worse.
Example: For months I have “rebuild Discourse for performance optimisation and finally use our own Postgres DB and Redis instead of the one bundled with Docker” on my bucket list.
Meanwhile I have collected a ton of bookmarks of GitHub READMEs, user posts on meta.discourse.org and blog posts by third party users. A significant proportion of the info I have collected is contradictory or outdated or whatever.
Result: Delayed for when there is more time …

Possible Solution

  • Why not put User Guide, SysAdmin Guide, Site Admin Guide into the Meta Category in every initial setup?
  • add a reasonable Category Description to it so that users clearly identify this as a place to go for learning how Discourse works
  • sticky message on top of Discourse for every new user
  • make the content of those posts available on GitHub so that the community can help improve these guides
  • add relevant “further info” links to the site and system admin guides where to find relevant READMEs, config examples and so


  • users just need to remember one place where to search for help
  • guides in a category make use of Discourse’s logic (post instead of PM)
  • opening the content creation to the community frees up resources of the developer team (reviewing rather than writing)
  • reducing dead links or deprecated information from various sources

I am very happy with Discourse and would gladly contribute to these proposed guides, as we are already busy with writing our own topics on how to use Discourse.

(Joshua Rosenfeld) #29

These don’t belong in Meta. They should go in the Staff category. I don’t think most sites want the Site Admin Guide to be publicly visible to all users.

That being said, I love the idea of making a visible User Guide that is pre-installed in Meta.

(Dave McClure) #30

Here’s what we’ve done to make the usage tips easier to find:

  1. Create a topic that duplicates the “usage tips”, so it can be more easily referenced.
  2. Update the “Welcome to [ForumName]” topic:
    • Brief description of the site purpose with a link to a topic discussing the vision in greater depth
    • Link to the usage tips topic
    • Link to topic about how it fits in with other communication platforms (similar to these: Slack and email)
    • Brief sections outlining some first steps to take and what kind of behavior we want to encourage:
      • Where to ask quesitons or give feedback
      • Update your profile
      • Keep reading
      • Show what you like
      • Start a new topic
      • Spread the word
  3. Pin the welcome topic globally
  4. Change the Welcome User email template to be the “Welcome to [ForumName]” content rather than the usage tips.

(Jeff Atwood) #31

Just to clarify one point, personal message (PMs) are not cleared until the user actually visits the PM. So in the case you’re describing, they did not just “clear the notification” – this isn’t possible for a PM – they visited the message.

(Christopher Semmler) #32

This is the reason why I used the quotation marks. They are not gone from a technical perspective. Due to (bad) user behaviour and information overflow they just forget it is there, since they do not expect this information to be stored in a message but to be “somewhere in the posts”. I have no idea or possible solution for solving this recurring problem other than manually pointing to the info.

My sample of course is not representative, but out of 10 users I asked to find this info, 9 searched for this in the topics. Just one remembered that this info was covered in a welcome message.

(Christopher Semmler) #33

You are absolutely right, I did not consider the ACL for the Meta category and totally forgot about the Staff category!

(Mitchell L Model) #34

(I have no idea whether this is an appropriate discussion for this post. Point me elsewhere if not.)

What about user documentation? I frequent stumble accidentally on features I didn’t realize were there, or realize what the icon meant, or exactly what would happen with some action. After posting a question here about documentation of search, I was pointed to the search options link you can click when you’ve started a search. (another thing I hadn’t noticed). Now, specifically, I want to understand the search features, and in particular whether there is more to know than what is in the search options.

(Mitchell L Model) #35

This confuses me, since the system does not, as far as I can tell, describe what actions are available and how they work. I saw the “quote as reply”, but didn’t parse the phrase correctly, and it took me a long time to realize what it did. (In fact I think I posted a question on the forum I was using about how people got those indented colored pieces of other people’s posts into their replies.)

There may be that initial page, but I don’t know any way to get back to it. If email was sent I have long since forgotten it, or didn’t even read it, writing it off as simply a welcome-to-discourse message.

Here is an important example of what is not apparent: how do I get to a list of all my own posts? OK, turns out that I have to click my name that appears when I click my avatar which I always click to see recent posts relevant to what I am following. Why should clicking my name do anything? Why is it even there?

(Juan M. Gonzalez) #36

Thank you! See also:

(Juan M. Gonzalez) #37

And there is really nice information for new users, with images, etc., in a private message received when joining this forum.

A hidden jewel that is good to review sometimes by clicking on our avatar, then on our name, then on “Messages”, then on the “Archive” folder if the message is not in the “Inbox”, then on the message “Welcome to Discourse Meta!”.