Discord is not Documentation
By @edent
· documentation Open Source rant watchy · 14 comments · 350 words · read ~8,270 times.
I'm going to be slightly contrarian and say that I like Discord. It's great to be able to get real-time help on a problem. And it is fun to see, again in real-time, what other people are working on and struggling with.
In truth, Discord is no harder to sign up to than Slack, Matrix, Gitter, IRC, or whatever. And of course Open Source projects will follow the maxim of "go where your audience are". There's no point posting everything to MySpace when everyone's already on Facebook.
Do I care that Discord isn't open source? Well, kinda. But I can open it in Firefox and it works just fine.
Discord is perfect for ephemeral communications.
But it is not a fucking substitute for documentation!
I'm currently getting started, and increasingly frustrated, with the Watchy development platform. They've effectively said "here's a barebones guide to setting it up - anything else, ask on Discord" - and it fucking sucks.
There's no API documentation - I have to scroll through a million messages to find anything.
I can't use search, because people don't know how to thread. So I can see questions but not replies.
When I do find replies, it's hard to know how relevant they are. A typical Discord chat looks like:
- Alice: What's the command to go fullscreen?
- Bob: Anyone know how I irrevocably format my disk without confirmation?
- Carol: Oh, yeah, it's easy. Just pass the
-fflag.
Errrr...
And then you get the people who get snippy with newbie for asking a question which is frequently seen! So infuriating.
I'm not necessarily advocating for the Four-Document Model - which has some critics - but I just don't understand why wouldn't at least collate all of the common questions and put the answers in one place.
Look, writing a FAQ is probably not the right way to approach comprehensive documentation. But if you can't even be bothered to do that, perhaps you shouldn't be releasing a product in the first place?
/rant
The complexity is the attraction - reflections on trying to use crypto
@Edent yes! Documentation requires actual documents
Big YES to this ☝🏼
Jebediah O. Kelp says:
It's a generational divide. People over 30 or so grew up with the Reddit, BBS, and message board model of organizing information. Zoomers and below prefer to have some sort of interaction, whether it's on Discord or through TikTok. Note that this interaction is not exactly the same as the one you have on Reddit, as there is more of a back-and-forth involved.
Come to think of it, if you could somehow train an AI bot on the messages and material in a given server, that could perhaps alleviate the problem by giving an instantly available Q&A function instead of rifling through what has already been posted.
Jeremy GH says:
A couple of thoughts: FAQs require Answers. Otherwise all there is are a lot (an ever growing number!) of questions requiring needing to be answered. RTFM requires there to be a manual to read.
And the bit that I find most frustatingly missed: the bit which answers the question 'What is this and why do I want it? Why should I invest money and effort in getting and learning it?'
Software Engineer says:
I believe the divide is between outcome and relationally focused people. People that want to solve their problems and move on desire good self-service ways to resolve issues. People that are relationally focused want to work with others on a solution. I don't understand the desire to be a cog in the machine, having to spin faster as more people are involved.
Fonzie162 says:
If a developer could not be bothered to write a documentation to their work, then I couldn't be bothered to even acknowledge their project's existance. If you tell me to "google it", then maybe you should work as the underwater robot vacuum cleaner for the pools, not as a developer. You should not absolutely be taken seriously and die off as a dev on github with a total of 300 stars and that's it. Maybe someone capable will see potential in your project and fork it, finish it and write REAL docs before releasing anything.
Tim says:
"In truth, Discord is no harder to sign up to than Slack, Matrix, Gitter, IRC, or whatever."
I tried joining Discord just now, and it made me complete 2 separate CAPTCHAs, and enter my birthdate. It's not an impossible series of tasks, but I'd definitely say it was harder than IRC. I never had to guess the species of a cartoon bear in order to join an IRC server.
KDDI G G if vm no g says:
Yeah, and it gets worse, many discords have some kind of spam protection implemented where you have to head to some third party webpage to get “analyzed” to determine if you’re a bot or not. If you have a new/barely used account or use a VPN you’ll likely be flagged as suspicious and it’ll demand another set of hoops to jump through.
Fuck all of that.
Feels right what you mention.
On a side note, I feel "ephemeral" chat places, can be a great starting place for: - inclusive feedback loop, so many users can ask questions, post comments - "working document" to solve user issues, and ecosystem bugs - store faq/solutions in the chat, but move them somewhere else, so they can be searched and read, like a docs
Definitely not the only community to have this issue - another of them (Beepberry) is also a SQFMI project, but there are a whole range, including some that are moving away from GitHub towards other spaces where it is difficult to track what is going on. I feel your pain!
I guess a way forward here is to set up a GitHub (or other) wiki and start keeping your own notes and then gather those kind of random comments from Discord into it...
Miscellaneous complainer says:
Couldn't agree more. I first came across discord as documentation when trying to find information related to MMOs I was playing, which, even though I hated the format I begrudgingly accepted as being the simplest solution for groups of maybe not so tech savvy people to share information in a free and easy way. But recently in my work/home server related hobbies I've been finding more and more software projects with outdated, incomplete or just completely missing online documentation with links to discord servers instead and it's really starting to grind my gears how many of these severs I'm expected to join and trawl through because “oh the website is being reconstructed at the moment sorry”.
anonymous said on :
Discord is not documentation | Hacker News
More comments on Mastodon.