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.
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.
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.
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.
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.
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.
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.
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.
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.
Add comment