One of the stupidest trends of all time.
There is FOSS alternatives out there like Revolt or just plain old IRC which is good enough imo. The Discord bullshit is so annoying.
I have been playing with the idea of a documentation.org. Something publicly funded (mostly through corporate and individual donations) that hosts technical manuals, white papers, guides, links to video tutorials (likely YouTube), FAQs, and even links to Discord and/or forums if they exist. Documents are public, free to index (no login to view), version controlled and held in perpetuity.
Obviously there is much more to it, but I think we have reached a point where something like it is required.
The very fact that you have to ask and wait for an answer is an inconvenience.
one time, I asked and got a reply that it has been answered already, followed by a rant of why the hell people were asking the same question over and over again. IDK man, maybe you could update the installation instructions in your readme, then people wouldn't be flodding discord with the same question over and over again.
(it was regarding the project being incompatible with the newest version of a library and you had to manually install an older version to get it to work)
Firstly, discord is entirely the wrong medium for documentation.
Secondly, documentation should be at least as accessible as the code. That is to say, if I can view the code without creating an account for some service, then I should also be able to read the documentation too.
Documentation is bad enough. But it's worse when that's the only channel to get support. I once read a project maintainer boast that they never read the bug reports and issues on github and if anyone had a bug to just chat him up discord. I mean, dude, no wonder nobody uses your software or takes it seriously. Much less want to collaborate on the development.
Agreed. I may not want to mix my discord identity with whatever project I'm looking at. I especially don't want to mix my personal online identity with my professional identity. I post too much politics for that.
Yes, this exactly! I still cannot fathom how Discord took off. It offers literally no advantages over forums, and introduces some massive disadvantages.
It took off because it was objectively the best catch-all communication option for gamers at the time. It's still the best option for certain use cases like that, but I'll never understand why people prefer it for projects, troubleshooting, updates, etc. It seems incredibly lazy and unserious to me. And the current Discord mobile layout is absolutely horrible, making for a totally miserable user experience.
RIP ventrilo and iirc 8(
My office has official chat (teams) and unofficial chat (Mattermost).
I don’t think there’s anything wrong with having a more casual discussion platform at work, which is what Mattermost had become.
At the beginning it originally had an appeal that anyone could create a voice chat server for free in a matter of seconds.
Teamspeak needed a hosted dedicated server. Skype was "calls" and not communities. Mumble was hardly known.
I completely accept why it took off but I hate where it has gone. it's over complicated and feature creeped electron shite
tbf discord is good for organizing activities in games with online multiplayer. definitely shouldn't be used for documentation in place of forums though.
You can create a discord server instantly with a handful of clicks for free. That's why.
Also, plenty of people use it for chat.
IRC > Discord
Modern web IRC clients like The Lounge or Convos can now display images, play mp3 and mp4 formats, and they have upload options. It can still be excellent for real time support, but I'm not so sure about documentation though.
Because it was easier to create a server in discord than ts3
Discord is better than IRC in any way except available clients, while also doing voice/video chat rooms so it replaced Teamspeak/Mumble. With the additional (at first) paid streamers and being free it took off especially with younger audiences. I remember how terrible Skype was and Discord just worked.
You don’t see its incredible simplicity as an advantage? That’s crazy
I don't think "simplicity" is in a FOSS evangelist's vocabulary.
Using Discord to support code is like trying to teach sculpture over the telephone.
you don't see a tool being too simple for the problem at hand to be a problem in tool selection? that's also crazy.
simplicity is a double edged sword. convinence is nice, but the internet feels a lot more homogenous these days than in the past
What makes it even more crazy is 90% of projects are using github/gitlab/gitea or some other modern git platform that literally has a wiki feature built in. And everyone and their dog either knows or could very quickly learn how to use markdown to write the wiki.
If you want a chatroom at least use matrix as it's open source and privacy respecting. Though IRC is better for a community. And good old forums are best.
Matrix
Open Element iOS
Start stopwatch
Syncing completes
Stop stopwatch
I have eight rooms added to the Matrix client! And Lemmings tell me it’s not Element, things are just slow.
Hoping they were wrong and I’m doing something wrong or this is totally atypical (e.g. connected to a really slow server).
FOSS is worth tradeoffs. Unindexable corporate software is regressive. But! Need some more speed over here! Individual chats/rooms are slow/buggy too.
Correct me if Im wrong but only contributors can edit the wiki. If I remember correctly you cant just do a PR to the wiki. Which is sad.
It's possible to allow anyone to edit a Github wiki. But I'm not sure whether edit permission can be set per page or wiki wide.
I've tried to use matrix... Is there a good matrix client? Like, one with admin commands? Maybe I just didn't "get" it, but it seemed not even yet half baked.
I will never understand "forums are best". I've tried, but they are worse in just about every aspect compared to any other communication system I've seen.
People just like what they like, I guess.
If the documentation is on discord, there is no documentation. Documentation has to be freely available, otherwise it doesn't count.
Friendly reminder that open source projects don’t just need coders contributing to them.
Technical writers are very appreciated.
I'm trying to get my feet wet in FOSS by making small doc PRs since I'm way too scared to actually touch code. It's not fun, but it is satisfying.
How does everyone feel about the "isolation" of information exchange? Specifically with systems like discord which encourage you to congregate behind a wall? Historically things like community forums were open to the public and thus indexable.
Hosting documentation on Discord is like hosting it on IRC.
While a useful tool in its own right, it's entirely the wrong choice for this job.
I have a strong suspicion that 90% of that shit is not being backed up. If a server gets deleted for whatever reason, all the documentation is extra gone with a side of never coming back.
No wayback machine, no wget, no open source. Add in server moderators can go rogue or get hacked at any given time. Recipe for catastrophic shitshows
Documentation is different from technical support and neither should be done on Discord.
Discord could be a decent place for technical support, the way irc used to be used, but unless it's super active with knowledgeable, helpful people, forums/GitHub discussions and other asynchronous comms channels make way more sense.
Otherwise it's like shouting into the void and the signal to noise ratio on my discord channels is really low.
Plus with forums and discussion boards they can be stickied and indexed to be searched. So the next time someone has that error message they can pull up that exact discussion.
Discord is not a place for technical support or documentation, or anything important, ever.
Search engines can not index discord.
archive can not archive discord.
Everything thats in discord, is in its own isolated bubble, that will disappear from history and time should the discord ever shut down, and even if its still up, its not findable by anyone searching for the problem.
Discord fucking sucks for anything but random bullshiting with friends over games.
It's actually quite worrisome, many projects exclusively have their troubleshooting or support on Discord now what's going to happen years down the road when all those Discord servers have closed or no longer active and the invite links expire this is going to be a vast knowledge base that's just lost to the world
I see your point, but couldn't you say the same thing about any forum?
"What happens when the forum shuts down? All threads discussing issues gone forever"
If you host a forum, you can easily access the database to move threads into some kind of archive if you no longer want to host it. It could also be moved to another server. Stuff like that.
Using a proprietary service instead is just a bad idea.
The web is on archive at least
Nope - cached/archived versions will continue to exist
best I can do is please react to the #roles channel with a ❤️ to unlock the channel. what's that? you're looking for a fix to an issue you're having in an older and supported version of the app? well sucks for you and suck my d*** we've already deleted that channel a long time ago who needs that old info anyway
Opened a discord link for info the other day...looked like a fucking Las Vegas casino. The.fuck.
How to install:
Step 1: git clone website
Step 2: run dependency install script
Step 2 again: Ha, ha, just kidding, that would be to straight forward. Please install this dependency installer program that only this and two other projects use. Pip grep panda cholotte poetry bash docker numpty anaconda jupternotebook alacazam. Oh, you don't have it? Well, I'm sure the project page will tell you how to install it and add it to path!
Step 3: Run " program name" and .... "insanely detailed description of what to do once the program opens"
Step 3 again: When you run it, get error "k*args passed null into program, so eat shit you can't fix this"
Step 4: Go to git hub issue page and see people have been complaining about this error for 6 months, but it was working back then when it's 12 dependency hadn't been updated yet. No fix incoming since the programmer was a chineese grad student that graduated 6 months ago and stopped working on the code.
This is why I like Docker. It's basically "works on my machine" as a service.
Similarly, I'm starting to really like dev containers. They're Docker containers with all the required dev tools already installed inside, and a config so that VS Code knows how to spin up a new container when you want to do dev work on the project. They use VS Code remoting - a VS Code server runs in the container and the regular VS Code desktop app connects to it.
I was recently dealing with a project that has some Ruby dev tools and it was 100x easier to deal with since they were using dev containers.
Well now I need to learn all about this.
YUP that's so relatable especially with ai-related projects because theyre all on python
If it's not search indexable it can go eat dirt
Never clicked on one of those Discord links, never will.
There are so many tools to make documentation for your project. LATEX is a great one, and you can use it to easily host your documentation online. And it's really not difficult at all to do by hand. If you can have it on discord you can certainly have it in a repo.
Maybe it's a cynical ploy to increase community engagement with their project by getting them into the discord. Regardless, it gives me The Ick. Very gross.
LaTeX is great, but I prefer Markdown for software documentation (bonus points if your flavor of markdown supports LaTeX-style math). Standard LaTeX is geared towards typesetting and formatting, which is great for reports and journals, but not so much for software documentation, so you end up with a lot of boilerplate. Markdown syntax is also more accessible to beginners, I feel. And if you have a really big project that requires features like cross-references, there's things like myst markdown.
Both are powerful tools, though with different strengths as you describe. I was thinking more with automation in mind. But regardless, anything is better than a discord server. Even .txt documentation!
I personally don't like LaTeX for documentation because it doesn't benefit much from advanced features of LaTeX, while being more difficult to read/write than Markdown.
Discord is great for building a community because it's the defacto chat service for communities. It replaced IRC and does that quite well. Having a place to casually chat with people more invested in the project has its advantages.
Now I really dislike it if they think discord can replace a wiki. Iirc discord added a wiki-like feature a while ago and it's terrible because it's not indexable by search engines.
I think you give Discord too much credit even with that. They're closed source and have very little openness with their data. We have no clue how they store and archive our data and conversations, or what they do with it. I don't think the open source community should trust Discord an inch.
I'm really hoping an open source alternative starts gaining traction.
LaTeX produces PDFs, which are hard to read on small devices. Just write a website.
LaTeX can produce .html with links. It can litterally generate an entire documentation website.
It's not really about the tools, we have plenty of tools, plain text, markdown, latex, web pages. Putting content to readable format is the easy part.
The hard part is knowing what to put down and how to organize it, and making sure that your documented explanations are actually understandable.
Particularly when you want to get traction going you might really want conversations to help you understand where the project needs fixing versus how documentation needs fixing and get a sense for what documentation might be helpful.
Imo this kind stuff probably because these "dev" having safe space on those discord servers rather than using something properly setup site/forum.
Heck you can make your own documentation using github/gitlab built in wiki or if you want something fancier, setup a site using JAMstack/static site generator, pick suitable theme then use gh page to host it.
I even more hate this stuff when the files is gated inside discord server, dude out of all possible file hosting services why the heck you would use discord?
Gates turn with money. That is the why.
I have been lucky and haven’t seen this. What a horrible thing to do.
I haven't seen this either. OP, you got a link? I'd love to see what kind of software is doing this.
Not exactly the same thing, but the xone (XBox One controller driver for Linux) project disabled Issues on Github and uses a Discord server instead. Which is stupid as heck, because I'm not going to join a Discord server just to check if someone has already encountered the same issue as me.
It's generally nothing big enough to have heard of unless you're looking into whatever niche it fills.
Only example that comes to mind is mechanical keyboard stuff. For some of the smaller / one-off designs there was a habit of "if you need troubleshooting, here's a discord link" instead of even minimal documentation. For "standard" stuff that used the same lil microcontrollers as everything else just a minor annoyance, but saw it with ones that used custom / no microcontroller too, where even a "you need X diodes, Y sprockets, etc" would've been nice.
Like OP tend to see it and move on and forget about it because it's not worth it. The few times I really wanted to get some service running on a raspberry pi or arduino or whatever and tried the discord was a handful of 'regulars' swapping memes that were annoyed I wasn't intimately aware of their codebase.
I've only got anecdotal stories but I have heard from my friends that ROM hack projects do this and I personally don't get it. If it’s to hide from the big N, Discord won’t back you there. Just teach your users how to use patch files instead.
TrueCharts (third party app repository for TrueNAS) does this and it drove me crazy until I eventually gave up and moved everything to Docker. Lack of serious documentation was just one of the many reasons.
Speaks to the fact that we apparently need better and new alternatives or make current tools easier to use.
Certain aspects of discord seem to resonate with people (unfortunately...).
Man pages are great as mentioned, but maybe not as accessible to some people. Are there tools to generate more convenient resources (e.g. wikis) from that? Similar to how generating technical documentations from (structured) code comments.
I mean, tldr exists but not for troubleshooting.
I agree with the point you make, we definitely need a more unified and better place for this.
A discord server with absurd amounts of over emphasised text, making nothing stand out, filled with emojis and broken up into different messages and sections at the exactly worst places for legibility.
No messages are answered in any channel, and you get amazing sense of all of the technology we have to communicate but zero ability to use it.
Not sure if everyone here knows the difference between documentation and discussion.
using discord for documentation is like using excel for a database
It's way worse. At least Excel lets you do database-like stuff. Discord is unusable for long-form posts or any info you want to keep long term.
still worse They own everything you write on discord
Name and shame!
This was/is my main gripe with Beyond All Reason (open source rts game) there is no wiki or forums - for an outsider it looks like 98% of all development talk is done in discord.
Though they do have a good basic knowledge base on their website about the game units and mechanics (but I would love dedicated wiki).
I once dm’d the maintainer of an open source project who got kind of upset at me for not posting an issue in GitHub. I got it, it made sense and the guy explained that it was all about visibility.
Except if they did, they would be complained at for "harassment"
It's not my favorite option. But at least use Discourse.
Any of the modern forum systems (Discourse, Flarum, NodeBB) is fine as long as it works. Previous-gen forum systems (SMF, phpBB, MyBB, Vanilla, etc) are fine too.
There seems to be some projects that allow indexing of discord. This should be encouraged more https://nextjs-forum.com/ is open sourced on GitHub.
Also stumbled on this the other day https://www.answeroverflow.com/
That’s only microsopically better than just discord. A (shitty, but somehow popular) chat service is not documentation, even if it’s indexed.
Fork it, clean it up, post it in their discord.
Not the dascord!!
Not the Dwildcardscord!!!
This is often done by people while the project is unstable. No need to write documentation that gets outdated every few weeks, when you can help people live in discord.
It shouldn't be done at all. If you're updating discord, you're writing something. That something should be, at the bare minimum, in a README file.
If you can't be bothered with Markdown, just do text.
I've never encountered this in the wild so I can't say for certain why a FOSS project would choose to do this.
Maybe they are trying to get more people on their server?
Discord uses a subset of Markdown for message formatting, so they'll be writing it regardless
And when the project is stable, they don't care to document it, either.
The first doc you write is the FAQ and let it handle the common requests -- no need to 'live' in discord. Locating that where more people can see it is normally obvious.
Sounds like a project I don't want to use until it finishes baking.
What if it is linked to foss social media like Lemmy and matrix ?
that's also pretty problematic, the very same way as discord, no difference just because it's ✨matrix✨ or ✨lemmy✨
edit: words
Can Lemmy be searched effectively?
The problem is the fact that the documentation exists solely as a series of what are effectively chat messages, not what platform those chat messages are hosted on. Markdown files or bust.
Anyone who does this should be blacklisted entirely
Is this related to Egalu?
Why censor the word "discord"?
Ah yes first world problems. The issue here is checks notes refusal to create a discord account on a burner email and use a search bar. Omg so scary
Discord is trash for reading just about anything
you can't honestly be saying that there are no issues with hosting documentation/support for a project exclusively on discord as opposed to a classic forum or wiki.
even ignoring the issues that you are dismissing (and would not exist on a better suited platform), the people using the discord server do not own it. discord servers have no backup functionality. what happens when an admin goes rogue or gets hacked etc? what happens when people get tired of discord for the next chat app?
you shouldn't have to use a burner email to download a videogame mod or view documentation for an open source project.
There are issues of course. I’m just of the view that answering questions and giving support to a project is perfectly fine on discord because of incredibly fast response times.
As a developer you really only have bandwidth for maybe one or two methods of communication until you get stretched far too thin. Discord combines threads and irc chats into one. That is incredibly productive from a support standpoint.
To me this is nothing different than asking someone to join an irc server for technical help. Most of the irc servers I followed no longer exist but the projects are still fine and they’ve managed. If anything it’s better because you actually have a search feature.
If Discord suspects that you’re using a temporary e-mail, they will demand your phone number.
Never happened to me once but I understand if you don’t want to use it for that reason
