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)
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.
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.
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 Patreon 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.
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.
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.
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.
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.
and so many people are already searching for solutions to problems and cant find them, because they are locked away on discord.
I fucking hate it.
and its only gonna get worse with the years to come, as more data is centralized in discord and locked forever away from search engines, or worse, lost with the discord gets deleted or if the company goes under.
and no ones saying to not have a discord. Just use it for what its meant to be used as. Social interaction. And stop using it for what it very obviously isnt, which is a information repository.
as annoying as havin all the answers on reddit was, at least they popped up in a search engine so you could find an answer to what your problems were.
I can’t wait until Discord have to start charging for features that are currently free (since they have to be profitable eventually), projects using it freak out about it, and end up switching to a different closed-source hosted system that’ll do the same thing years later. It already happened with OSS projects using Slack that migrated to Discord. People just don’t learn from the past.
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.
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.
A agree with everything you just wrote. Discord is the platform of choice for many projects because most people are already there, so it increases engagement (and often enough some people actually ask for an official discord).
I personally prefer projects to use matrix, despite all it’s faults. Some already do.
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!
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.
Yes, this exactly! I still cannot fathom how Discord took off. It offers literally no advantages over forums, and introduces some massive disadvantages.
I may be getting old, but I think D*scord (I’m all for cencoring it like a slur) isn’t any more simple than a phpBB or something similar was. Quite the opposite actually, at least for any user trying to navigate the the darn thing.
Maybe navigating is the wrong term. It’s just impossible to find stuff relevant to me on discord. On any given larger server, there may be a few channels I could be interested in - but they are just a single chat log, often with lots of off-topic spam, and many different people having almost separate discussions at the same time. On any given larger phpBB, stuff is mostly separated into different threads with all the off-topic posts being delegated to a single thread. It’s better searchable and better organized.
What even is “relevancy”? Their search is just a search by matching keywords. There isn’t a magic algorithm discord uses. Every time I had an issue with some sort of bug or function I just search for specific keywords and 9/10 times I find something. On the odd-chance I don’t then I’ll behave like a human being and ask. I just don’t get what’s wrong with that? You can already limit those keyword searches with specific constraints so you don’t get much noise.
Joining via server invites that guide you through sign up, no dedicated server to host (I know, major downside for people who don’t want all their stuff centralized to Discord’s servers), GUI server admin tools, etc.
I think devs tend to vastly overestimate how tech-savvy the average person is. Bring up hosting, DNS, port forwarding, terminal, etc. and they’re going to nope out pretty quick. Provide an option that lets you do everything from a single GUI and they’ll use it. Enough people use it and eventually the tech-savvy folks have to follow because that’s where everyone is.
That’s absolutely not to say that it’s a good medium for documentation. I will always prefer well-written and organized docs first and searchable forums/issue trackers/SO second. But that second group has a lot of tech elitism and devs who are (perhaps justifiably) short on patience, so Discord seems a lot more accessible to newbies who are asking the most basic questions.
tbf discord is good for organizing activities in games with online multiplayer. definitely shouldn’t be used for documentation in place of forums though.
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.
Of course an IRC chat won’t be used for documentation, I meant for general chatting and support. Also I didn’t know that, hopefully I’ll be able to replace the absolutely proprietary discord with it.
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.
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.
I’m unfamiliar with Directional Chat outside of things like VRchat, how that work if you’re not manipulating your position in space relative to other users?
This. Whatever can be used on devices without admin rights, such as work or school devices, for “free”, will get picked up by normie worker drones and college students and minors in droves.
It’s been pretty handy in a lot of ways, but yeah I do hate what it’s doing to indexable information and it’s only a matter of time before it goes for IPO and suddenly gets way worse seemingly overnight…
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
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.
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
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.
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.
i can understand your point of technical support, but what the op is calling out is when the only source of docs/support are discord.
i’ve had multiple experiences firsthand where I needed basic information about a piece of software that really should have just been on a readme or a wiki or something. instead my only option was to repeatedly ask a discord tech support channel and wait for someone who cares/knows about my question to actually answer me.
unless the options are limited, i’d rather simply pick a different solution than be forced to ask a busy discord channel for tech support.
Assuming you used the search feature on discord and no results came up, then you would be the first person to have ever asked that specific question to the developer. What makes you think that would actually be on a readme?
that’s a good point - i might be letting my dislike for discord-as-a-wiki color my argument. i will say that i’ve had mixed results using the search - sometimes there are no results and sometimes there are plenty of irrelevant results. that’s just what you get when basically hitting ctrl+f on who-knows-how-long worth of conversations instead of a purpose-made knowledge base.
i still think that a dedicated wiki/forum/repo available on the web for anyone with the url is far better suited to this purpose than discord is. discord is (arguably) good at being a chat app and its features aren’t well tailored to being an easily navigable knowledge base. it feels like jumping through unnecessary hoops to have to join a server on the app i use to share memes with my college roommates to get help troubleshooting some software, or worse, to get access to the only official release of the software.
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…
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.
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.
Add comment