Disclaimer
Not trying to blame anyone here. I‘m just taking an idea I‘ve read and spinning it further:
Intro
A lot of people use free open source software (foss), Linux being one of them. But a lot less actually help make this software. If I ask them why, they always say „I don’t have the coding skills!“.
Maybe its worth pointing out that you don‘t need them. In a lot of cases it’s better to not have any so you can see stuff with a „consumer view“.
In that situation you can file issues on github and similar places. You can write descriptions that non technical people can understand. You can help translate and so on, all depending on your skills.
Other reasons?
I‘d really like to know so the foss community can talk about making it worthwile for non coders to participate.
Using GitHub is a skill of it’s own, and requires knowledge of coding practices. It’s hugely confronting to someone without coding experience
I code but I found it to have quite a learning curve.
Maybe the first step is to develop a “how to use git for improving documentation on a FOSS project” lol
Yes, absolutely but github (which is only an example, mind you) has a lot of consumer friendly accomodations like github gui and cli.
You can edit stuff directly in someone elses repo (or so it seems) in the web browser. I know you have to do a branch and a pull request but thats something that can be worked on.
Thanks for making my point. :)
Woooooooooooosh
Wow. Great addition. Have a nice day.
The “woosh” is because we’re trying to point out that the average person probably doesn’t know how to use git cli and make coding documentation.
I knew that. I‘m saying just because the average person doesnt use it does not mean nobody uses it.
Since you’re trying to build bridges with this post, I just want you to know that everything you mentioned in this comment is far beyond a non-programmer and sounds totally incomprehensible. It’s jargon soup. I don’t say this to dunk on you or anything, I just wanted to let you know how high your own skill level is, because it can be easy to forget sometimes. People without those skills won’t be able to follow this kind of explanation.
I’m interested in where the limits to expectations lie here. I’m not trying to be a jerk when I say this next part but I do worry I may come off that way but I’m trying to figure out the boundaries of what a “reasonable” expectation is so I can make tasks like this easier for my own team (completely unrelated to this project but it’s essentially the same problem).
Is it not reasonable to expect people to type into a search engine something like “GitHub help” and then poke around in the links that come up?
… Well I’ll be damned, I tried my own method before commenting, and the first link that comes up is a red herring, how obnoxious. I was hoping it’d be a link to the docs, not GitHub support. I guess I just answered my own question: no that is not reasonable.
As a technical user, I am still at a loss for how to help a non-technical user in an algorithmic way that will work for most non-technical users x.x guess I’ll be thinking about this problem some more lol
(I guess I’m rambling but I’m gonna post this anyways in case anyone wants to chatter about it with me)
It’s super hard to know this and there won’t be a consistent answer because everyone is different. You have to meet people where they are.
I think you did answer your own question on this one. I’ll also say that as a somewhat technical user but still not a heavily technical user like some people here, GitHub is a really baffling website. It’s hard to even figure out how to download something from it. I would strongly encourage anyone who wants to reach non-technical users to avoid GitHub. It’s made for programmers and it doesn’t make sense to anyone else without training.
That’s fair. Part of my job is converting non-technical users into technical users by teaching them things like problem solving approaches that are supposed to help them teach themselves how to learn whatever they need to actually do their job. I don’t teach them what to do, I teach them how to learn what to do.
I agree that you gotta meet people where they’re at, but I try to teach them how to poke around any code repo site, like GitHub or gitlab, so they can use it. Usually I point them to the docs and start by pointing out my favorite parts so that they have somewhere to kind of start by themselves, but it is a skill set that can be practice, or at least I am convinced it is.
I’m not very good at this part of my job, but also, no one is, so it’s not a bad thing, I just want to do better. I guess I never thought of it from a truly non-technical and not wanting to be technical perspective before. This could be solved by a secondary interface designed specifically for this kind of user. It would not allow code download or interaction, but it would allow for issue logging. I might put this idea in my ever growing project list because it sounds like it would be a useful product…
I think that sounds like a good product, too. To be honest the problem with GitHub from my perspective is there isn’t a front page so to speak. If you’re a non-technical user who just wants to download something, there should be a nice big “download latest version” button front and center.
That was exactly my point with the linked xkcd too. Not sure how they interpreted that as being in support of their post.
Thanks for the heads up. Yes, I‘m indeed trying to help and apparently some people really want me to stop but I wont. I‘m happy a few actually appreciate it.
The jargon soup is not intentional, I was trying to head off a couple smartypants that will tell me that editing a repository in the browser actually just makes a branch.
You can’t do it right anyway. If you facilitate change, people will crucify you. So I just take hate and dont care at all.
deleted by creator
Tried submitting a relatively simple change to the Ansible code base once. Added an option to the telnet module to support different ports. Submitted a pull request. Was told I needed to change and update the documentation. Didn’t know how to do that, and I didn’t get any guidance, so I abandoned the pull request. Kept on using my own hack until someone else added the option.
Make contributing easy, and more people will contribute.
I absolutely agree. This needs to get a lot better. But talking about this will facilitate change. Thanks for taking part.
Pretty much this. I had a similar experience on a different project. If I ever submit a patch again, I’ll make sure to run it by the maintainers before I start coding.
Maybe it would help to have some kind of boilerplate language and framework for contributing that other projects can make use of.
Solution should not be technical.
CONTRIBUTING.md should be very simple to follow and have all the steps necessary to submit a successful contribution.
Have a section in there for first time contributors. Link to a YouTube video outlining the basics if need be. Explain the process from the very beginning. If you want fresh talent to contribute, educate them on the right way to do so. (Perhaps this is an opportunity for boilerplate language. However, best current practice may change over time.)
Be pleasant to and patient with contributors who fall short. They may never have contributed anything before. In that case, you are an ambassador not just for your project but for all open source projects. Don’t be a jackass who drives away talent just because they didn’t do something exactly perfect.
Because UX/UI is just as painful as coding.
Fair enough but writing a readme isn‘t, right?
That’s the most painful part of all.
Asking for a friend: do you code? Because most coders say this and thats my initial point. :)
I’m not a coder but I relate to being a lot more attracted to the idea of problem solving than writing a well-formed document that communicates ideas clearly, haha.
Well, then I can relate because I have this exact situation on lemmy (and IRL) but I write good handbooks and readmes.
I‘m more of an entry level coder and I havent studied IT so I have no idea what the dev thought making something but I know what would have helped me to use it.
What use is a readme written by someone who doesn’t know the code, doesn’t know the internal designs, the design goals, the plans of the current maintainers, anything? It’d be no better than asking ChatGPT to write it for you.
I‘m sure a lot of people who correct text, add references, structure and pictures to a readme would disagree with you.
I‘m not sure if you‘re a coder but it you are, you should know that coding and usability are two entirely separate things.
Oh…
You don’t mean the readme file. You are talking about the manual, or the explanations on the website. Yeah that can make sense. Though I would still say it’s weird if you’re not too familiar with the direction the application is going, but an experienced user can of course help create better texts and pages for that.
Easy, just click the whatchamacallit, and add that little do-hicky!
This is why all my methods are called ˋdoStuffˋ.
Exactly. Thanks :)
Yeah, that’s a good point, but the readmes that I’ve seen written by those who wrote the code themselves are not much better. Sure, they know what it’s all about, which is precisely why it oftentimes isn’t much help for a user.
What’s needed is someone who’d read the initial readme (written by the guy who wrote the code itself) and ask questions about the parts that were “too straightforward” to be included, or weren’t explained clearly enough, or to bring down the general overview back to Earth.
And if there’s yet another person who’d go over this second pass, and keep it from being too dumbed down, even better. Keep it to the level of the average user. That requires knowing the kind of person who’d likely use the program.
Why does it have to be documenting internal designs, architecture, and all that? Why not app user manuals or install guides or any of myriad other sorts of documentation?
Just because one specific scenario may not be suited doesn’t mean no scenario is suited to what op is proposing.
I mean first, what kind of projects are we even talking about, libraries? APIs? Apps? Command line tools? Etc?
Because the technical writing needs vary depending on what kind of project. They don’t all require coding skills for success.
deleted by creator
deleted by creator
deleted by creator
Technical Writer is a skill. It’s a fairly well paid one too.
Being able to make good documentation is hard.
User Experience (UX), user interface (UI), and graphic design are all also surprisingly difficult. Much of which is integrally tied to the code.
I came here to say something similar.
Just writing documentation alone, is a skill worthy of a full-time job! Of course, there’d be people who can volunteer their time to do that, but without someone with such skill at least taking a look and making sure it’s understandable to someone who’s got no idea what’s going on? Let’s just say that open source software help documentation is filled with such examples.
Yeah, I probably should think about taking money for it but making descriptions and manuals is just something I like to do. And there are a lot of people who also do this but dont call it „technical writing“. Often it is things like doing glossars or explaining abbreviations. That helps a lot.
Because every time you try to suggest more modern interfaces you run into the type of people that like it when software looks utilitarian and bland.
Seriously how many people have complained about how GIMP works and looks to the point where Gimpshop exists but they still haven’t made any improvements.
run into the type of people that like it when software looks utilitarian and bland.
Pretty much 99% of programmers. Which includes me tbh. All of my early web admin panels were grey boxes. Grey everywhere! Thank god for Bootsrap.
Which I can understand. Everyone is entitled their own opinions.
I’m a programmer and I find dealing with other programmers frustrating and pointless if you discuss anything that’s not programming related.
They’ll happily discuss algorithms or language paradigms for hours but if you mention design, UI/X, marketing, etc they shut you down claiming some greater-technical reason for the feature.
Lemmy is a good, recent example. As part of being a web dev I’ve also done a lot of SEM. The devs have a Github issue for making readable URLs. They completely refused to consider it claiming other technical requirements for not allowing it. Any arguments outside the narrow technical reasons are discounted. So what if readable URLs will help people find the site through Google easier (because Google will better index the site). It breaks X feature and we don’t see a need. No discussion and no listening.
If devs don’t see a strict technical need for something they ignore it at best and at worst they insult you for being an idiot.
Hubris and ignorance make it a PITA to deal with them.
Ohhh I know that one! This happened to me a lot already. Some devs are completely socially incompetent although brillant programmers. I mostly call them out on their bs if they start it. Happened a couple times in this comment section alone.
This is why I’m so glad my degree forced us to have UI and UX classes to graduate. I definitely picked up a lot from those that have helped me be a better developer overall
If you give me an extremely easy way to submit feedback, then I will. Don’t expect me to go way out of my way, though, researching how to get into contact with you and such. I don’t actually care that much, you know how many products exist out there, right?
But, just by way of example, an early access game I started playing recently has a very convenient button in the main HUD for submitting bug reports/suggestions, and I’ve been considering different ideas to submit with it. Any I cannot throw out as impractical or counter-productive will get submitted eventually. I’ll also report bugs I encounter, of course.
I will not look up your team’s forums just to talk to you though.
Absolutely relatable. Thats why we need to make this a more streamlined process.
Like every foss software, be it games or whatever, should have an easy way to report bugs.
One thing I see different is foss-software and -games: You getting something for free and asking for „everything be dead easy“ without helping it become dead easy is not the most healthy.
You cant compare foss software with for profit software that either takes your money, serves you ads or outright sells your data. Thats only making the world a worse place.
The devs dont make money off you, yet you‘re saying you‘ll not give anything back except if they pave your way to it. I think you should pay for foss software then.
Side thought: If someone just puts an email address for receiving feedback somewhere where I’ll see it, I’ll use that too. A UI button isn’t really necessary, just so long as I can send the feedback without having to do my own research in order to do so.
I can write an email though.
Simple but great idea. Thanks for elaborating.
In principle I agree with you. But people sitting behind their keyboards will also be fairly pragmatic about it, pretty often.
Thanks. I dont get the pragmatic part yet. Care to elaborate?
People suffer from limited attention. Trying to take a purely principled approach and investing the energy to give back to every project you may want to can become impractical. Especially if one had a busy family and professional life too, it may just not be worth it, however much someone may wish to help.
It’s just the organization of priorities, and simply put, sometimes a few minutes really is too much to ask in certain circumstances.
Thus, removing as many hurdles as possible is probably a worthy investment of a devs time if they want large amounts of feedback. Pragmatic, not based on any ideas of what might be right or wrong, but simply what is probably going to happen most of the time, with no consideration to why that might be or what might be better. Pragmatism is frequently unethical.
I agree. Giving back to every project you end up using as much as you gain from it is impractical but I‘m merely talking about giving back at all, either through work or through money.
So, do I understand correctly that you assume that a dev would usually go the way of least resistance hence pragmatic?
No, not necessarily. I don’t think a dev usually would, or even should. It depends entirely on why they’re working on whatever the project is. To put it in more mathematical terms, I’m essentially saying that the amount of feedback any particular dev receives on their project is going to be a function of only really two major variables: How many total users they have, and how convenient they make it to deliver the feedback to them.
Those two variables are most, but not all, of what governs what happens. They can do with that information whatever they wish. If they want a lot of feedback, they should make it easy. If they do not wish a lot, they should not make it easy. That’s all, really. It’s not particularly high level thinking or anything.
I think its a skill nonetheless. Boiling something down to a merely binary or the most basic structure is not something everyone can do. Thanks for elaborating. You might be a great fit if any form of “foss improvement pact” ever comes to existence. Because most people who have deep technical knowledge lack social skills and the other way around. But being able to think very laterally or change mindsets is rare.
Going Medieval has a Bug Report button in the top right corner during gameplay at all times. It’s an early access game, and the devs have been actively updating it and adding new features over the past couple years since it first went into EA. What’s there is great, and you can spend tons of hours just building up your settlement.
Totally. Everyone has a threshold of pain in the ass above which they don’t care enough to contribute.
Some want to contribute but find that having to use git, let’s say, is too big a hurdle, otherwise they’d totally contribute. Ok, so lower the barrier to entry. Make it less of a pain in the ass.
You don’t need to make it so easy that any idiot on earth can submit changes or the project will be flooded with bullshit probably. But for those who would otherwise be dedicated contributors but for that one thing, fix the one thing.
If you can’t code (or have limited coding skill) but know the system well, one of the best ways to contribute is by writing end-user focused documentation. Write about things that confused you. Improve the “getting started” guide. Add more articles to the docs. Create video tutorials. Things like that.
Exactly. Thanks for mentioning it. :)
I think a major deterrent from contributing things that aren’t code is that whoever is implementing it might think their design is better just because it’s theirs.
Try talking to the GNOME team, for example. You will never be able to get a suggestion past them because they’re always right and you’re always wrong.
Even when you prove them wrong and they backpedal, they are still correct and you are still wrong.
I ran into basically this with home assistant. Commented on an issue about an integration to point out that it didn’t work at all, and to support another user that had rewritten it in a way that fixed it. The approval dev jumped in to say that they only permit single changes to be approved. That’s fine, I guess, but to fix the issue multiple changes were necessary. The user that had rewritten it then tried to limit the change to a single fix, but because that didn’t resolve the issue they blocked the change. The integration still doesn’t work and the user stopped trying to fix it.
I totally believe you.
That kind of rigidity in software design leads me to believe more people need to read The Pragmatic Programmer.
I, of course, do not; because I am already a pragmatic programmer.
Gee if someone wants to fix an issue they can be my guest, that way I don’t have to deal with it. It’s not that people aren’t pragmatic it’s that they are little generals of their own world and they don’t want to give that up even if it would make the world better.
I’ve met some absolute Napoleon’s in my time programming. I don’t know what it is that attracts them, perhaps it’s that programmers historically tend not to have very good social skills in general? I don’t know, but it’s weird. You’d think they’d all be total nerds and be somewhat deferent, but nope.
I mean, you‘re not wrong. But I think you’r example applies to far more than you think.
I think the reason we are in a dystopian hellscape is because people need to be always right and never say sorry. That is why the master manipulators are running our countries and economies. Because then you can be always right, poor and exploited but always right.
The movie idiocracy is a perfect depiction of our current world.
But I think we can make it happen nevertheless. We need to tackle points like yours and take them serious. This would be excellent in a code of conduct for the foss community to take on.
You will never be able to get a suggestion past them because they’re always right and you’re always wrong.
I said similar in another comment. The Lemmy devs are the same.
Lemmy only exists because Reddit kicked some fascists off the side a couple of years ago and they didn’t like that. So, yeah, they’re not stable.
As someone who knows how to code and wants to contribute to FOSS, there is very little guidance in doing so even if I half-know what I’m doing.
I agree. I‘m also often confused. I‘m not adept at coding but a lot of low level programming, scripting, config files and so on I can do.
We need a more streamlined process and a behavioral code how to treat contributors. Something like the fedi instances that have decided to band together against bigotry and such.
Writing documentation of all kinds seems like it would help a great deal. I would be hesitant to file UX complaints, because those tend to be ignored by programmers who focus their limited available time on fixing defects and shipping features.
Where are all the programmers who enjoy improving UX and enjoy the challenge of changing legacy code? 😉
Fair enough. There seems to be a hole in the plan there. I think most UX programmers are sitting on their 5000$ chairs writing code on their 10k$ mac for their billion $ corporate employer. Kind of joking but I bet its not far from the truth.
Considering how often feedback is met with “where’s the PR”… that’s why.
So you‘re saying they’re unfriendly/impatient with non experts? That is a real problem imo and needs to be addressed. Thanks for the feedback.
I’m a coder myself, but… yeah, it’s a definite problem. Of course the feedback can sometimes have its own issues.
Absolutely. I have made mistakes myself and I know its hard to understand that others think differently than oneself.
Some people are better at technical writing, some are better at coding, some better at UI/UX design
I don’t think op is asking people with zero technical aptitude to jump in writing user manuals.
Just because you don’t code doesn’t mean you can’t contribute in some fashion. If you have the skills to improve a user manual, wiki, or help file… Why not right?
You got it! This is how we actually beat the corpo trash. :)
I do with translations.
Cool! I like the modern translation tools where you can submit sentence by sentence. Weblate I think is one called. Works great.
I’ve been doing a lot of translations for Debian into my native language, and the most important factor there is being part of a translation team of people. Many times the english original is ambiguous or just poorly written by a programmer, and with a team you can get help and find the intended meaning and its proper translation. We read each others translations and come up with constructive criticisms.
To me, what makes or breaks good work is the organisation and cooperation between people: the community. I believe the great challenge of FOSS is the organisation of people and their efforts.
OP, your post has inspired me! I’m going to write a small python program that works as a multiple choice questionnaire that spits out a comprehensive ‘contributing.MD’ at the end of it.
When I’m done, will you test it for me and give some feedback?
Abso-f*cking-lutely! Thank you for the feedback! :)
An organised, easy way to do this would be great. Kind of like a test audience for FOSS.
Right now, people basically have to appoint and organise themselves as reviewer, which is a big ask.
Yes indeed! Feel free to dm me if you‘re interested in helping with this. I feel like now that so many people responded positively, we could discuss where to go from here.
Good luck! Organising is hard work.
I can code or do errands, and am willing to help out a bit. I’m not sure how much time exactly I can devote to this, but if you’re stuck on something and can’t find anyone else to do it, I’m a good call. I might switch back to lemmy.sdf.org depending on how broken it stays, same username though.
Sounds great. I‘ll let you know if I come up with something.
