Discourse documentation

(se oli tonnin seteli) #1

How can I find it? Like, any of it. End user, admin… doesn’t matter, I just need to know where it is since I’ll probably have use for different types of documentation at some point so once I know where it is, I’m set.

Currently I’m just trying to find a changelog since a new version came out and I have no idea where it is and Google isn’t helping.

(Robin Ward) #2

Our documentation is designed to come from the instance as you use it. For example, all new users are sent a private message with instructions on how to use the site.

If you are the administrator, you are also given several topics with detailed instructions on how to get started customizing your Discourse.

The idea behind the approach is that if you give access to all the documentation at once it is daunting, but if you introduce it to people as they need it they’ll find it much more accessible.

Of course beyond that we have the howto category on this site with more advanced guides.

(se oli tonnin seteli) #3

Thank you for your answer, I understand what you mean and pretty much agree.

Discourse is not really all that complicated, but it is different and even though it’s very easy to get started with, some things are not so obvious.

Assistance on the go works very well but it’s still only complimentary to, not the equivalent of a proper documentation.

There’s also ergonomics to consider; the popups are messy (sometimes two on top of each other) and at times even feel like a distraction. And how do you access that information again if you forget?

Right now it feels as if though some features are simply hidden, such as polls. Another very good feature that is hidden is “select and quote” that me and my users found out about by accident.

Admin settings are great, but they could be just a little bit more verbose, like for example how custom user fields work. Everything is exceptionally well documented to the point of running a functional forum, but from there on it really does feel like a treasure hunt :wink:

I’ve noticed that people here on meta don’t mind answering even the simple questions, but I really did not want to bother anyone with this as I assumed that this kind of question would - and if not, should - be completely unnecessary.

While I am trying to make the most out of this post by providing insight and constructive feedback, the treasure hunt might lure in people with a shorter fuse and that’s discouraging to you and even if you do get people talking, not all publicity is good publicity.

This, how should I put it, accidental vagueness makes Discourse seem both off putting and incomplete, which it is not - it’s amazingly complete.

But nothing is stopping us users from compiling a feature & configuration reference topic with a wiki post for a manual that could be easily copied and I might just get started on that when I have the spare time…

(John Oeffinger) #4

I generally think peeling back the onion layers as the user needs it is a good approach. That said, I have found this approach very inefficient for my learning Discourse as an Admin on top of my day job. Our instance is hosted and I started exploring Discourse back in late October. I could find some information on several of the initial topics I needed to address. @codinghorror and @sam have been very helpful in resolving several of our initial items. There are questions I still have and that I still have not stumbled upon an answer in searching Meta and specifically in browsing the How-To. The How-To is geared much more to the non-Hosted Administrator. I’m one of those who needs to understand the context of why something works the way it does before putting it into practice.

One concrete example, this past week I stumbled across the video from the presentation by @codinghorror at Habit on community development and a brief introduction to badged. I had no interest in understanding badges at the outset. Once I watched the clip, and several others, badges, their importance, and the context of their development made a lot of sense. I would have loved to have known about badges and how they work back in early November…but you don’t know what you don’t know. I clearly didn’t know how to phrase the question correctly.

I do think it would be very helpful to have a cheat sheet [documentation] broken down for Admins that provides some context for key items to be considered in setting up a Discourse instance. This could be very helpful to those of us who are not developers and use a hosted instance of Discourse. I would also be happy to contribute to this. I can’t take the lead because I just now feel comfortable enough with the software to begin bringing in several of our project teams. I’m also contracting with one, and possibly two people, with whom I have built online communities with. One or both may be able to help. I do love what the development team is doing and how the Discourse community is assisting in creating the Discourse ecosystem!

(Jeff Atwood) #5

Well that’s funny because it’s described in the welcome PM every single new user gets…

Here’s a screenshot:

May I humbly suggest reading what the system puts in front of you as a start?

(⛰️) #6

While I agree with the sentiment, what bothers me is:

Which means not one person was absent-minded, but what sounds like an entire community. As to the size of that group remains to be seen.

And having more than one person ‘not getting it’ is probably something more than simply ‘not reading it’.

(Jeff Atwood) #7

Yeah, well, there are lots of people who don’t read anything you put on the screen, ever. But you don’t expect that from the community leaders.

(⛰️) #8

Again, I agree. May I make a suggestion?

I have dabbled in the idea of forcing users to complete badges to even post something. I have had the exact same case in the past, time and time again. “It is there, just, please, give it a read.”

I understand the frustration.

But nothing will be solved by saying to read it. It must be requirement to read it to use it.

Don’t know if this can be done with badges, but if so, it might make things easier that way. If someone tries to post or anything, they cannot and instead are ushered to the private message they recieved upon account creation.

Sure, that might upset the admin, but, this is the result as we see here. And this is nothing against @tonninseteli. I have ADHD. Sometimes even I do this. And my attention must be halted to complete stop (ie, removing posting ability) and my actions halted to read something before continuing.

I doubt this will help, but, ehhh. It’s food for thought at the most. And it can always be something for the admin to turn off if they wish. As you said to me in another thread, it’s about covering your own ass.

(Jeff Atwood) #9

Not really. There are lots of ways to get a quoted reply:

  • highlight text then click any reply button
  • click the quote button in the editor (it’s the first one)
  • manually copy and paste the text from the post

In the process of doing that, you’d eventually figure it out, since highlighting text causes a button to appear above the highlight.

So part of this I read as a complaint in this form

I did not magically understand everything there was to know within 60 seconds of seeing the software

whereas I would propose

Anything worth using takes a little bit of time to learn, and you will reliably learn it as you go. Furthermore, things that are fun to use reward exploration with power user features that may not have been immediately obvious. This might even be part of the design.

With a corollary that, if you are a leader in the community you should be reading the basic instructions that are put in front of you. And if you don’t, well, that’s on you.

(⛰️) #10

Not speaking about quoted replies here. I am speaking of the fundamental problem underlying this one. But thank you for the explanation regardless.

Then forever more things like this will crop up. Sure, you can’t force an admin to read (I think?) but I will see if I can make my admin ux easier by having my users walled until they read something. I have done it in the past for some things with great results.

(se oli tonnin seteli) #11

While I admit I might not even try to remember where each little crumb of information was afterwards, I have to asses multiple sources of information on and choose the ones that will get me where I’m going to dive deeper into at work on a daily basis, so this is likely to happen, especially if I expect there to be a reference to go to once I’m done with my current task.

My first priority after build was to go through settings and look for options that I might want to disable for security reasons etc. I did not have any plans on quoting anything for quite some time, as I was more concerned with possible bugs, dealbreaking flaws or missing features.

Once everything seemed to be in order and I was confident the software would indeed be a good choice, I let people in and we continued from there, figuring it out as we went along and we’ve had loads of fun - less than ten people blasted the forum with a couple of thousand messages in a few weeks.

I like how Discourse still surprises me with neat tricks I’ve always wanted from a forum software every time I use a feature for the first time, and that the tooltips and popups actually provide important information, but I still stand behind my words; the way Discourse spoonfeeds information is only complimentary to a more complete reference, including not just how to post, but everything else important to both users and admins.

I think it’s condescending, although not completely unexpected, to imply that someone has not even tried to read documentation, when they are wondering how to do exactly that.

(Tobias Eigen) #12

Have you all seen this topic about onboarding? I think the landing on discourse is indeed not very soft for newbies, especially those coming from mailing list world and not already familiar with forums. This is a shame because the potential is so huge to bring these worlds together and to get the benefits of both, but the process is painful and slow. On my sites users ask for screenshots and guided tutorials - I think the real answer is in some sort of onboarding process that visually walks you through the basic functions and benefits, much like online services like gmail and facebook do to introduce new features.

(Alessio Fattorini) #13

It might be very very cool and useful from my point of view. Why not?

(Ron Shannon) #14

It’s true some don’t read what’s put in front of them, but it’s also true that others are readers who want and need some traditionally organized, cohesive documentation. (I have looked at the how to category – not exactly what I mean.) If someone wants to help that happen, how should they go about it? Is there an existing team and/or project?

(Jeff Atwood) #15

I posit that these users are the least likely to need such documentation though as they are A+ students by nature.

They’ll find or make what they need because they are diligent.

I’m more of a fan of the “Just in Time” sort of documentation, so the most relevant questions are

  1. Where is the user when they need this information?
  2. How can we show just the part they need to them at exactly the time they need it?

(⛰️) #16

I like that style of docs. The only caveat at the moment are the few ui quirks that will eventually be sorted out with time. I think that’s why some are asking for it all to be written out in black and white at the moment.

(Ron Shannon) #17

I think actualizing JIT documentation theory is a great objective (did read the blog post), and someday it will be here, but in the here and now, it’s taken me (Mom always said, “Always an A+ student!” :grinning: ) many hours to diligently attempt to locate the info I’ve needed – not always current, of course – just so far. Yes, A+ students are likely to be diligent enough to figure out what to ask and probably find it – if they can afford the time. But that begs the question, “At what cost, and why should it require the level of diligence it does, now, even for A+ students?” Before I commit this to production use, other competent, busy people, who have to multi-task all day, every day, will need to grok it too. Not in the future, however desirable that will be, but now.

My query is not a critique of you folks, who have done, and still have your hands full doing a fantastic job. [Thanks again!] It’s not a critique of a JIT preference or vision. It’s just a question whether others may have already started a docs or wiki project somewhere that perhaps I could contribute to.

(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.