Why are open source projects so broken and apathetic if they are run by idealists? [closed]

I read your question as, "Why are free and open source projects difficult to use and lack documentation?" This is fundamentally a matter of the economics of available development resources, so I'll approach the question from this angle.

I agree with a comment above that people contribute to free and open source projects for a wide variety of reasons. A few of them include:

• they have a personal need for software that performs some specific functionality
• they think proprietary software is unethical and want to develop a replacement for some specific piece of proprietary software
• they are paid by their employer to improve a piece of open source software

I'd expect (without actual supporting data) that the first reason is the most common, if only because it's so easy for any developer to say, "I wish I had software that did X; I'll start writing it today." As Eric S. Raymond says, "Every good work of software starts by scratching a developer's personal itch."

It's easy to imagine free and open source software is developed in pursuit of an idealistic vision to create the perfect software, or to rid the world, once and for all, of proprietary software. Perhaps that's true for some deeply idealistic developers, but I'd say most people who write it (and even the idealists, when they're actually sitting down to put fingers to keyboards) are just trying to make software that is good enough to scratch their personal itches.

Of course, everyone has different needs, and the software as it exists may fail to meet those needs, or fail to properly document how to use it. The problems, from the perspective of developer, might be:

1. It's difficult to know what other people's problems are with your software/documentation, and
2. Once you do understand what problems exist, it's challenging to balance developer time between making the software that you planned to make against fixing deficiencies identified by others (or just balancing which of those externally-identified deficiencies to fix first!)

Documentation is an especially thorny problem to fix, because it's often "good enough" if you already have a sufficiently prerequisite good knowledge: if you already know how to make the software do X, or already know exactly where to look, or already know how to set environment variables, or already know how to set compiler flags, etc. Instead, it's great to write documentation that is complete, and accessible for a particular audience, and helps refer more novice users to the right prerequisite resources! That's what great technical writing can do, but not all developers are up to such a challenging task of technical writing, or aren't interested in spending what precious time they have on technical writing over the (more immediately-gratifying) task of writing code.

Obviously, this can leave users such as yourself in a very bad position! These pain points arise because the software might be able to do what you want -- and it will do it for the author and inner circle of developers who know how the software operates -- but they haven't taken sufficient care to make the software accessible to you, and outsider with whatever level of technical expertise you have. From such a position, it's easy to see how developers might laud the greatness of their software while simultaneously creating an environment in which it's difficult for others to use, as you identify in your question.

Once substantial advantage is that you have the ability to scratch you own personal itch here: if you wish to save others the pain of using the feature you've struggled to use, then you can write your own documentation and submit it for inclusion in the project. Or, if the feature doesn't yet exist, you (and, perhaps anyone else who want to participate in your crowdfunding effort) can pay someone to modify the source code and make it exist.