I hate how devs use Discord for documentation. All the info on there is fleeting.
If you have a problem, you can’t just look up the solution. You have to ask in the Discord channel, hope someone is friendly enough to repeat the solution. And if someone else has the same issue, they have to do it all over again.
Wargaming deleted their forums and fully switched to Discord for all discussion. It’s frustrating seeing a bunch of search results for my questions and half of them lead to nowhere
Having tried it, search is horrible. You have to look up the help to even know how to filter the search to a specific channel, by default it searches the whole server. I never managed to find anything, I had to ask again instead…
I hate how devs use Discord for documentation. All the info on there is fleeting.
Guilty as charged, but in our defence we mirror most of the info from/to GitHub best we can. Also you can make the information somewhat less fleeting by pinning comments to a channel, using forum channels, or creating channels where users only have read access. Of course this doesn’t prevent the data from going away if Discord does, but to be fair the same can be said about almost all other services as well. GitHub servers get ransomwared and they don’t pay? Yeah your changes until their last uncorrupted backup are gone now unless you had backups of your own.
The reason why we use Discord in the first place though is network effect. The amount of reports and questions we get on Discord is simply no comparison to GitHub. It’s more simply because more users already have Discord than do GitHub leading to a lesser barrier of entry (account creation/program installation), especially for gaming related projects like ours. Of course this creates some added bureaucracy for keeping track of important reports from Discord. It’s kind of manageable to do manually, but I have been looking into ways of having a bot transfer messages/threads to GitHub by simply replying with an !issue4321 command or something. Sadly I’m pretty sure we wouldn’t get half the reports we do on Matrix/IRC/XMPP/whatever, same diff if we were to switch from GitHub to GitLab basically.
Lastly, a server owner (or someone given the rights by them) can get an API key that enables them to dump the full server logs to disk. So if you really want your Discord server content to be indexed by search engines the possibility to just host a copy of your logs as a static website is technically there (we admittedly don’t do this yet, not sure if there are existing projects for this).
Know what data source isn’t fleeting? Forums.
Guess you never were a member of a forum with private sub-forums that went out of maintenance? That info is just as gone as our Discord logs if the company croaks tomorrow. And the public part is only available if it was mirrored to web.archive.org or something, which isn’t guaranteed either.
In summary, yes Discord isn’t the shit, it’s just shit, but the people are there. If the mountain won’t come to you, then you must go to the mountain. ¯\_(ツ)_/¯
Absolutely, what we have on the Discord in the way of documentation is a straight forward install guide with one screenshot and a download link (of the GitHub release) and a FAQ channel, which is basically just links to the GitHub for a good part of the answers. We also automatically mirror our changelog there. But that’s it, and it’s all on GitHub as well.
What gets sadly lost on GitHub sometimes is “emerging events” like a new release of ours or the game we mod breaking something, where we will get yelled at on the Discord immediately and might have a hotfix release out before anybody even managed to create a proper GitHub issue.
Edit: Oh and temporary workarounds. If we figured something out on the Discord it doesn’t get posted to Github necessarily even if there is already an issue. Hence why I’m looking into having a bot for that instead of literally having to copy and paste a message.
I’m old enough to remember years of people complaining about overzealousness in closing threads as duplicate on forums, even when the issue might have been somewhat specific but the user could have just been unable to correctly recognize all factors at play with their issue (things like firewall, dependency versions and their configuration, environmental variables, hardware etc.) or the issue was actually caused by new bugs or API/ABI changes.
But at least there was some redundancy reduction and things were usually well categorized and tagged and many places actually implemented some pretty decent fuzzy search for similar existing issues. Instead we’ve ended up in both users and maintainers really wasting their time on something already resolved much more often.
If you don’t have time/are too stubborn for that, good luck skimming through tutorials to extract the info you need and pasting/adapting others’ code all while hoping there were no breaking changes since the snippets you want to use were published. At which point you might as well go ahead and browse type definitions and function signatures if you’re lucky to use something written in a self-documenting style.
I hate how devs use Discord for documentation. All the info on there is fleeting.
If you have a problem, you can’t just look up the solution. You have to ask in the Discord channel, hope someone is friendly enough to repeat the solution. And if someone else has the same issue, they have to do it all over again.
Know what data source isn’t fleeting? Forums.
Wargaming deleted their forums and fully switched to Discord for all discussion. It’s frustrating seeing a bunch of search results for my questions and half of them lead to nowhere
It’s not a good documentation thing by any metric, but can’t you just search? Discord has a search button!
Having tried it, search is horrible. You have to look up the help to even know how to filter the search to a specific channel, by default it searches the whole server. I never managed to find anything, I had to ask again instead…
It shows you all the filters except the one for the channel…
It shows it. You either glanced over it or didn’t scroll down, plus Ctrl+F is a common shortcut anyway.
While discord isnt great for dpcumentation, you dont have to ask and hope for a response. Well modded servers have forums in the server.
Guilty as charged, but in our defence we mirror most of the info from/to GitHub best we can. Also you can make the information somewhat less fleeting by pinning comments to a channel, using forum channels, or creating channels where users only have read access. Of course this doesn’t prevent the data from going away if Discord does, but to be fair the same can be said about almost all other services as well. GitHub servers get ransomwared and they don’t pay? Yeah your changes until their last uncorrupted backup are gone now unless you had backups of your own.
The reason why we use Discord in the first place though is network effect. The amount of reports and questions we get on Discord is simply no comparison to GitHub. It’s more simply because more users already have Discord than do GitHub leading to a lesser barrier of entry (account creation/program installation), especially for gaming related projects like ours. Of course this creates some added bureaucracy for keeping track of important reports from Discord. It’s kind of manageable to do manually, but I have been looking into ways of having a bot transfer messages/threads to GitHub by simply replying with an
!issue 4321command or something. Sadly I’m pretty sure we wouldn’t get half the reports we do on Matrix/IRC/XMPP/whatever, same diff if we were to switch from GitHub to GitLab basically.Lastly, a server owner (or someone given the rights by them) can get an API key that enables them to dump the full server logs to disk. So if you really want your Discord server content to be indexed by search engines the possibility to just host a copy of your logs as a static website is technically there (we admittedly don’t do this yet, not sure if there are existing projects for this).
Guess you never were a member of a forum with private sub-forums that went out of maintenance? That info is just as gone as our Discord logs if the company croaks tomorrow. And the public part is only available if it was mirrored to web.archive.org or something, which isn’t guaranteed either.
In summary, yes Discord isn’t the shit, it’s just shit, but the people are there. If the mountain won’t come to you, then you must go to the mountain. ¯\_(ツ)_/¯
You are not alone in this.
Prior to discord I’d get maybe a bug report/month. After, about 1/day.
Simply put, the barrier to entry is huge.
However, documentation on Discord (other than simple end-user instructions/links to git readmes) is sort of stupid.
Absolutely, what we have on the Discord in the way of documentation is a straight forward install guide with one screenshot and a download link (of the GitHub release) and a FAQ channel, which is basically just links to the GitHub for a good part of the answers. We also automatically mirror our changelog there. But that’s it, and it’s all on GitHub as well.
What gets sadly lost on GitHub sometimes is “emerging events” like a new release of ours or the game we mod breaking something, where we will get yelled at on the Discord immediately and might have a hotfix release out before anybody even managed to create a proper GitHub issue.
Edit: Oh and temporary workarounds. If we figured something out on the Discord it doesn’t get posted to Github necessarily even if there is already an issue. Hence why I’m looking into having a bot for that instead of literally having to copy and paste a message.
I’m old enough to remember years of people complaining about overzealousness in closing threads as duplicate on forums, even when the issue might have been somewhat specific but the user could have just been unable to correctly recognize all factors at play with their issue (things like firewall, dependency versions and their configuration, environmental variables, hardware etc.) or the issue was actually caused by new bugs or API/ABI changes.
But at least there was some redundancy reduction and things were usually well categorized and tagged and many places actually implemented some pretty decent fuzzy search for similar existing issues. Instead we’ve ended up in both users and maintainers really wasting their time on something already resolved much more often.
If you don’t have time/are too stubborn for that, good luck skimming through tutorials to extract the info you need and pasting/adapting others’ code all while hoping there were no breaking changes since the snippets you want to use were published. At which point you might as well go ahead and browse type definitions and function signatures if you’re lucky to use something written in a self-documenting style.