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.
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.
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.
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.
Exactly. The problem is admins encourage it to be used for technical discussion as there are channels dedicated to that. And Discord has picked up on the need for structured discourse and have reinvented forums, just shittier and more closed.
The way to prevent all this information going into a black hole is for admins to stop encouraging Discord for this kind of usage, in addition to users moving to more open alternatives. Godot for example is moving in the right direction. It has recently opened a shiny new Discourse instance, now the only thing thatās left is to burn the Discord forum with fire.
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.
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.
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ā¦
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.
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!
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.
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.
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.
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.
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)
While I think its a huge deal to require email addresses for publically accessible information, the rest is true. Although, upvotes and and different posts 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 or optimal for the task, just better than discord.
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.
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
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.
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.
