- cross-posted to:
- programmerhumor@lemmy.ml
- cross-posted to:
- programmerhumor@lemmy.ml
You must log in or register to comment.
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
Opened a discord link for info the other day…looked like a fucking Las Vegas casino. The.fuck.
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.
First thing that comes to mind is https://devdocs.io/about
Also I’d rather just have these things in the repository.
Aren’t you basically describing readthedocs.io?
In the most technical terms, yes. The idea is not new or bizarre, but I see the same missteps repeated. For starters, the venture HAS to be a nonprofit with zero need for monetization. It will also need an inviting and easy to navigate user interface, accessible to the most nontechnical of users. You need to have a massive document library from multiple large players from day one, so you need to have a lot of contacts.
As I said it’s not fully cooked, but I have spoken to a few people that could help me make it happen and they seemed open to it.
Please consider a pattern for doc review. I don’t mean reviewing the doc against the project for fitness, as that’s the job of each project to maintain and review their own docs; I mean by a technical writer who can de-localize (you only think I mean ‘internationalize’) the document and make it syntactically and logically correct against a generic, classic style guide.
The rising popularity of really bad errors is definitely turning me off from videos or documentation from a few sources with a lot of churn. It ruins the flow and it robs the assumption of authority which I’d argue is an important part of any documentation.
That is a good idea. I am fairly certain I could get funding and/or loaned resource time for English, Spanish, French and German, but crowd funding incentivized localization for other regions is brilliant.
All chat programs are shit for long term accumulation of knowledge. Discord, revolt, IRC, they’re all just as bad for it.
Forums are where you’ll find people who are actual experts discussing because they want to be able to easily reference previous posts by other people.
we just need IRCv2 which should add chat history
How do you replicate a conversation like this in a IRC format?
https://www.advrider.com/f/threads/yamaha-wr250r-threadfest.936588/
IRC at least you have text logs, but I agree.
Where’s lemmy in regards to this?
Lemmy/Reddit style platforms are good at generating short term discussions, it’s threaded chats.
The main features that makes forums the best to accumulate knowledge is bumping and linear discussions. There’s only one discussion that everyone is following if they want to talk about a specific subject, the knowledge on that subject is centralized and keeps accumulating instead of requiring to be constantly repeated because the previous thread is lost to time. The linear discussion means you don’t have to go back up and start reading a different branch to know what some other people are talking about (which often times leads to having many people basically saying the same thing without realizing it), all new replies appear in chronological order and people quote others to provide context when necessary.
Look on old school forums for more “boomer hobbies” and it’s ridiculous how long conversations can keep going. I provided a link in another reply but the Yamaha WR250 thread on ADVRider has 428k replies since 2013, all that is possible to know about this motorcycle is in they thread and pretty much any question you might have will have its reply in there. There’s car forums with discussions that have been ongoing for decadeS!
Meanwhile on Reddit of you want to ask a question in a thread that was started 24h ago you’re shit out of luck, no one but the OP will know about it. On Lemmy? Everyone sorts by top 6 hours.
In regards to the advrider comment, I don’t find those ridiculously long-running threads all that convenient even though they are very useful. In your example the WR250R thread could have multiple subtopics being discussed at once in the same thread which I find frustrating.
For example, one guy might ask about tires and while that’s being discussed another guy shows up asking about a big bore kit to make more power. Now there are two discussions happening at the same time and all I can do is view the thread chronologically. Then someone else shows up asking what oil everyone uses. Then someone new joins and says “Hey it’s not possible to go back and read through all 2300 pages in this thread, what GPS are you all using?”
Like sure it’s great that all the information is in that one thread but navigating through it only in chronological order can be super frustrating.
ADVRider is more of a “motorcycles in general” community and they try to limit the number of “subcommunities” (the Wr250 thread is in the Thumpers subcommunity), but a WR250 specific forum would have the discussions you’re talking about split up.
The real solution though would be for a “Reddit style forum” to exist, where people can create new subcommunities however they want but to have it work like a forum instead of having threaded discussions that don’t get bumped.
It actually drives me a little nuts that the 500 EXC-F thread is under Thumpers and not under Orange Crush. I get that it’s a Thumper, but it’s also a KTM. Why have a subcommunity based on engine type when all of the other engine types are in manufacturer-specific subcommunities?
There’s another foss alternative called Apache2
That’s not the point. The point is that pointing to Discord means that there simply is no documentation.
I meant it more as a communication platform, not nescessarily for hosting documentation. Either way, using a forum is still pretty good alternative
I only want the documentation if you have to fax it to me
Whatever, Mr. Stallman.
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)
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.
And when the project is stable, they don’t care to document it, either.
There is a gazillion options without having to use a login walled proprietary solution.
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
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.
Not the dascord!!
Not the Dwildcardscord!!!
Fork it, clean it up, post it in their discord.
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”
Nope - cached/archived versions will continue to exist
The web is on archive at least
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.
That’s why FOSS ends up forking and forking
Imagine “stealing” a project just because you can write sensible documentation.
If it’s open source and the license allows it, I wouldn’t consider that stealing. If a fork gets more popular than the original, then it either addresses a major missing feature of the original or is simply more active. If this displeases the original dev, they can hopefully work it out with the maintainers of the fork. This is a feature of FOSS, not a bug.
Another way to think about this is that those projects that have a more structured approach to documentation have a better chance at lasting longer, attracting more contributors, and making more lasting impacts
Is it stealing if it’s been dead for 30 years? Or is it modernizing it?
What? We are talking about discord documented software.
This is why going back to the moon is so hard, when msn groups closed back in the early 1970s we lost alot of very precious knowledge.
Is this a joke?
No, there was MSN in the 70s but communication was made through a machine called Microtron. They are largely lost to the world due to being made from degradable PCB plates.
Yes, obviously.
Everyone knows the moon isn’t even real.
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.
Well, we left reddit for beginning to plant a walled garden, so…
I’d say we left to plant a community garden. Anyone can see it, Anyone can join or start their own.
If it’s indexable it’s not a walled garden
We left because the previous garden is getting walled and this one isn’t.
Yeah… That’s what I said…
Not clear if you talk about here or there I think
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
It’s a good thing discord saves all your data. Thanks discord
Discord provides no way to backup and restore a server. There are freemium third party products and some rudimentary open source tools that do so, but yeah, it’s wild how much information about open source software (this also applies to the game development community) is just in a proprietary walled garden with a single point of failure.
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”
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.
I can’t understand why someone would want to do that. Maybe it’s my help desk and IT upbringing, but for the few software tools and things I’ve made, if you chat me without filing a bug/issue on GitHub, I’m not gonna help you.
To play devil’s advocate here: sometimes there are genuine reasons to try and request support before making an issue. I’m not particularly smart, nor too techy. If something isn’t working, I’m just going to assume I’m an idiot and I’ve messed something up. If I can’t figure out how to make it work, my first post of call will be trying to find a community related to whatever isn’t working, or on smaller projects I might try and reach out to the Dev. Opening an issue always feels like a “hey, your program isn’t doing what it’s meant to do, here’s what’s wrong with it, please fix it” and not “I think I’ve fucked something up, can you please help?”
I suppose it depends what you’re developing though.
You can open an issue and say exactly that
And then get it insta-closed withing 20 minutes saying that “this is a problem with your setup, not the software” even when “my setup” was literally setting up their project using their documentation (docker compose files).
That is how developers treat people with questions that they deem “stupid.”
It turns out their documentation was wrong and some environment variable that they said was optional, was not actually optional and the service would go into a reboot loop without it. I figured that out no thanks to the devs.
Yep, and if it becomes a frequent request, add clarification to the readme / wiki / documentation.
Also, if you push folks towards issues, then they become indexable by search engines! So even if you have a solved problem you can at least find that… Discord? It’s a black hole.
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.
Never clicked on one of those Discord links, never will.
What if it is linked to foss social media like Lemmy and matrix ?
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.
Can Lemmy be searched effectively?
that’s alao lretty problematic, the very same way as discord, no difference just because it’s ✨matrix✨ or ✨lemmy✨
I don’t think a proprietary forum that requires an email address to view information is equivalent to lemmy. It’s publicly accessible, open source, and can be federated. Matrix still requires some kind of account to view information if I remember correctly.
Sure, but that’s not the only problem with discord as a documentation. I’d argue, from a practical standpoint that that’s not even really a big problem. The problem is that a stream of random conversation, sprinkled with memes and jokes, with multiple parties having a chat is the absolute possible worst way to find information (and it’s not even guaranteed to be there if someone hasn’t asked; or maybe someone asked, but never got answered)
That is true, though upvotes and and the different threads can help cut a lot of that crap. Also offers the ability to be indexed. I personally still throw the word reddit at the end of a search if I really can’t find anything and one of the top comments usually has what I need. I agree though, not perfect.
It’s possible to view matrix rooms without an account, but it has to be supported by the server as it has to load the conversation history from other servers over federation before showing it. I’m not sure about how long this currently takes.
I think the key is whether it’s indexable by search engines and can be archived by archive.org. Any chat service fails miserable at this and is thus not acceptable for documentation.
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
I think we fixed that for someone a few months ago, maybe you can scroll back and find it. I think the guys handle was user-something, might have been around May…
Reading this made me feel a bit of anxiety
Dicsor server
dicsor pls
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.
