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. :)
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.
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.
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!
Exactly. Thanks :)
This is why all my methods are called ˋdoStuffˋ.
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.
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.
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.
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.
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.
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.
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. :)
Because my skills when it comes to coding (absolutely none), is using the program until it breaks and telling someone what happened from an uneducated stand point.
If you are going to make things for “idiots” you need to hand it to “idiots” for testing.
Makes total sense and reporting stuff from your viewpoint is great. :)
I do with translations.
I would be happy to give feedback, but I have no idea how to do so. On a few occasions, I have responded to posts, such as like on Lemmy where someone asked for suggestions to improve KDE. I still have no idea how to use GitHub at all, much less to provide feedback. I know GitHub is something I can work on to learn to interact with the FOSS development community, but it’s probably a major barrier to the non-tech people that use FOSS.
Now that I think about it, I’m thinking it would increase non-tech interaction if developers of FOSS engaged the community through social media. Like, get on Lemmy, Mastodon, even Reddit, FB, and Instagram, and engage the community in these discussions. I think that will definitely increase engagement from the non-tech users, though some of those sites may feel like a betrayal of values. It seems like an interesting ethical dilemma.
Edit: So I looked into it for KDE in particular. They actually have a Wiki that simplifies user engagement. Maybe promoting these avenues will also help engagement.
It takes a certain kind of a skill set and experience to be able to translate this “consumer view” into something that can be acted upon by a developer.
Sure, the skill set can be developed, the knowledge (about software development, the available technologies, and having an idea of what is and isn’t feasible in the first place) can be built up, and the experience (communicating with developers) can be accrued, but that really stops a lot of people from even thinking of contributing.
Perhaps a subset of the (open-source) community can help in developing these (skills, knowledge, experience) among interested people. Teach people how to look for issues, bugs, or come up with feature requests; teach them how to put these into a form that’s easily understood and appreciated by the developers, and finally, teach them how to communicate with developers without losing the “non-techie user POV” which makes their feedback valuable in the first place.
IDK though, having read what I’ve just written, it seems to be quite a task.
I think you are totally on the right track but yes, the task is massive. Thats why I asked. I‘m trying to help with making it happen. And asking questions is one way of doing so. :)
It sounds like we need PM’s to act as a liason between developers and end-users to bridge the difference in jargon and way-of-thinking.
I never thought I’d say having PM’s were going to help. Ironic.
I think just spreading awareness is a step in the right direction. Most people I know just have no clue and continue purchasing the established mainstream programs. I encourage people to give GIMP a try instead of buying photoshop, or OfficeLibre instead of MSOffice. Most of them are ecstatic to save a couple hundred bucks. The more people that use FOSS software the more likely we are to get the support it needs.
I have to write userscripts to make websites bearable, software UI is not as customizable( bright white background at night, tiny 9pixel fonts, huge empty margins and content crammed into 200x200 boxes,lots of tiny cryptic icons crammed into toolbars that suppose to be menus,etc )
because a lot of foss devs, contributers and even users are so extremely hostile when suggesting ux improvement/report bugs/etcetc for end users not like them that frankly I dont wanna bother. Same reason I don’t report bugs
maybe first tackle that situation before you ask people to throw themselves into what effectively is a lion’s den to mauled by fossbros who can’t get over themselves
No. First I ask people for feedback and the feedback you‘re giving now is important and valuable. Thank you for that.
I‘m not asking peeps to do anything. I ask why not. Then I take that feedback and try to implement it. :)
Have a good one.
