some of you might've seen this post floating around recently, and while it might be fun to read and laugh at, i think there's something to really be said about these kinds of frustrations when it comes to code projects like this. (that's not to say the project in this post is guilty of any of this, and in fact, it's quite the opposite. the user is clearly in the wrong here, but i digress.)
there's a certain trend i've noticed in recent years where developers will put up one of their projects on places like github, and then give almost no instructions or documentation on how to use said project. obviously, this can be forgiven if it's relatively new, not really intended to be public, or even just not intended for the average end-user at all (as is clearly the case for the reddit post from earlier). but there have been a number of examples where a project fully intended for regular users is entirely hosted on github, and has virtually zero explanation on how to use the app as intended. for some reason, a lot of developers will often just throw a github link at you and just expect you to know how to navigate the weird ui and developer jargon to get to what you want.
please! fucking! stop! doing! this! the average person does not understand github and doesn't want to spend 20 minutes figuring out how to begin downloading an app! and don't just say "oh just open the releases tab" because people don't know what "release" means either. i guarantee you the average person does not associate "release" with "download"/"install", and i know this is true because i have literally seen people here on cohost being frustrated with this exact problem.
people also like to say "well just look at the readme", and there are not one, not two but three problems with this "solution" as well:
- the average user probably doesn't know what a "readme" is either
- the readme is always located at the bottom of the page on a github repo, where it's incredibly easy to miss completely.
- even if the user manages to find the readme, they're likely gonna have further trouble deciphering it, since most readmes are written primarily with developers in mind. instructions for setting up dependencies and configuring IDEs and shit. once again more total nonsense regular users wont understand (and in some cases i've seen confused users who thought setting up those dev environments was required to install the app!!!)
the thing that pisses me off the most about all this is how github literally has tools to make this easier for everyone involved. you can set up a basic, static website using github, completely for free. you can make a simple installation instructions page you can link people to without any of the surrounding developer jargon to confuse them. you don't even need to know how to make websites with standard web languages like html. if you can write markdown, you can make a website! it literally could not be easier. here's the documentation for it. of course you can make a more advanced site with your own HTML and such, but the point is making a basic website is incredibly easy. and yet, for some reason, developers don't want to do this??? instead, they'd rather have all the information (if any) on a fucking discord server that can't be accessed by google, let alone archived in any way.
yes, please join our discord server, a completely unrelated service you need to sign up for, where you can find all the documentation or troubleshooting steps on [XYZ] feature of our app, but not before you have to solve a captcha to prove you're not a bot, read and accept the rules, get pinged by 3 different welcome bots for some reason, and figure out which non-meme channel has to do with the project in question. now you get to try discord's text search, the usefulness of which is entirely determined by the type of device you're using! and also you'll probably have to use it because the pinned messages are just filled with more memes and inside jokes or are otherwise unrelated to whatever you need. just dont forget how you have to guess which of 500 different keywords might be used in relation to the thing you're searching for. and if you're lucky enough to have to resort to actually asking someone in the chat, have fun waiting 6 hours for someone to come online and respond only to call you a fucking idiot because you obviously just need to do this and that and also download this random file from 7 months ago that fixes everything and blah blah blah blah.
it's extremely tiring, all of it.
there's nothing inherently wrong with using github as the literal hub for a particular project. you just need to understand it is not easily accessible for everyone by default. just because you and a lot of your friends might know how to use github, it's important to understand that experiences, skills, and knowledge are not universal. the same idea applies to discord, for a couple other reasons.
having a discord is nice as an option to discuss things with people in real-time, but it should never ever be the only option. same for project announcements, and especially for documentation and troubleshooting. discord might be free, but it's not open. and again, your experiences are not universal. not everyone has or wants a discord account, and even people who already have one might not want to join a discord server just to find one random piece of critical information to get an entirely unrelated app to work.
i guess TL;DR all i'm asking is for developers (but anyone, really) to be more mindful of other people outside their usual circles.
that's it, really.
ok bye
