Improving Discourse documentation

This is exactly the problem with discourse documentation.

As much as it can be “ok” for some to go hunting for topics, it’s not a documentation. It’s having the users, and worse, the admin/moderators have to hunt for information.


No, it is not. And that has been, and still is, the biggest lack of Discourse. I don’t know if I’m too rude now or something, but tendency of acting here is too dev-centric — if you don’t know you can always read the source at GitHub. CDCK hasn’t too much motivation to start building good documentation to users — including admins too, of course — because theirs target is hosted big corporations. So for them minimum level plus community help for freeriders (who are doing big part of bug hunting and UX propositions :wink: ) was enough. Except then we would need more freely use of tags…

Was enough wasn’t just typo or low level english skills. CDCK/team has started build up better documentation and I’m totally sure that after some time side topics as this will be just echoes from past.


As developer/user communities go, discourse is well above average. Errors seem to be corrected quickly, feature requests aren’t just ignored, especially if there’s a reasonable use-case for them, and the online staff (paid or volunteers, I’m not sure how you tell who’s what) are pretty good and fairly patient at coaching us newbies along.

Yeah, the documentation needs work, but writing good documentation is expensive and time-consuming. Moreover, developers often don’t write good documentation because they’re just too close to the product, they don’t see it as users see it. Being too close to the code is also a product testing issue, though in many open source projects the user community does a good job testing things.


Sure it is. So is writing good code too. Good quality human work is quite often expensive. But code and docimention are tied up together, and documention starts to be expensive at that point when no one does it. Otherwise it is just cruicial part of a product as is coding including testing, design, UX/UI etc. But devs quite often hates documentation because they just hate to do it, there is noting sexy in it, plus they are quite often really bad at it :wink: But because owners of companies, and other supervisor, are similar devs they just don’t care that guys are cherry picking what they do, and don’t do.

But now I’m drifting to too general things that are way too much off topic. So I’ll off and pointing to documentation because it is evolving right now.

1 Like

I absolutely agree with this. I’m a developer with over 20 years of experience at this point, even if I pivoted into platform engineering in the last years.

That is well clear in here when you ask for a suggestion and developers (I assume? I can only see that they are part of discourse itself in their title) comes and tell you that it’s not and will not be because they decided so.

OT from here

I already said this: there is a difference between being opinionated in your tech stack and being opinionated in your product. You product should cater to the users use-cases, in the limit of reasonable, not being “your ball and if others don’t like they can go somewhere else”.

I’ve already 5 new project started and thanks heavens we had someone in our community that know a bit about Ruby and it’s going to explain some basic of the flow of discourse to us in the next days so we can start writing some plugins that provide the features we need. One above all, making the Category Mods not a joke.

The Users are receiving emails even when everything is set up to not send email notifications support topic had evolved a little so I’ve split it off into a couple of fresh ones in other categories to give each of them some space to breathe. :+1:


I can think of one open source project where the developers tend to work on things they’re interested in, not on things that might make life easier for users of that product. Use-case is always a matter of perspective, users of products have a different view of use-case than developers do. Developers tend to think of things users do as ‘just more data’, and often don’t see how a small change might make a HUGE difference in usability. (I’ve done my share of system development, and I’m sure I’ve had that attitude at times.)

So far I can’t say I’ve seen that kind of attitude with Discourse development, but I’ve only been here a month.

As to being too close to the product, I’m currently going through the exercises in a book on Ruby development, A simple ‘hello world’ app took me 3 hours to get working yesterday, mostly because the book assumed familiarity with an AWS IDE (cloud9) environment that I didn’t have yet, so I’d click on something and it’d undo the changes I just spent 10 minutes typing.

And then there was an issue with getting a preview of the working app to display on my browser, which appears to be due to security limitations that both Firefox and Chrome have put in their browsers since the book was last updated. After an hour or so of web-searching for solutions, whitelisting the IP address of my laptop and desktop worked, though I still have to go through an extra step to get the preview to display.

1 Like