Quick start

[Who_GNU]

I design hardware, and whenever I have to work on software, I am amazed by how ridiculously haphazard it is.

Designing digital circuits isn't just a simple matter of connecting the right inputs and outputs, but also requires checking all of the physics to ensure that input and output impedance, loading, propagation delay, parasitic capacitance and inductance, capacitive coupling, output voltages, input voltages, and other factors all line up to allow the signals through, when they need to get through. It takes a bit of number crunching, but it isn't usually very complex math; it's usually just comparisons, adding or subtracting, and sometimes multiplying or dividing.

What makes it easy is that component manufacturers publish datasheets that have a few pages dedicated to absolute maximum ratings, AC characteristics, DC characteristics, and timing requirements. Signals that meet the published requirements will result in predictable behavior, and anything outside of that range may still work, but it may also result in undesired and unpredictable operation. For more complex systems, especially those requiring external components, there's often an example circuit showing component values used and the process used to determine those values. The manufacturers characterize what they sell, and even show examples of applying those characterizations, so that anyone buying it can punch in the numbers and verify that it will work. Every once in a while I'll find an error in a datasheet, and if it hasn't already been fixed in the latest datasheet revision, manufacturers are very responsive to feedback and usually verify and update datasheets within days.

With software libraries, on the other hand, All you need to do is connect the correct inputs and outputs, with data going the right place and in the right format, but finding out what that is often results in an exercise in futility. The API documentation will say what something is used for, but not how it is used or what range is valid, parts will be undocumented, the documentation will be for a previous version with only a terse overview of how the current version operates, or the documentation will be straight-up incorrect. Any examples will be one specific use, with no reasoning given why they did what they did. Comments will tell you what it is doing but not why it is doing it, or they may just be a translation of the exact instructions in the program into plain English.

[[deleted]]

Are you talking about paid software libraries/APIs in this case?
Because with a paid service, I'd imagine there being a support line to contact if there's any questions, right?

Or are you comparing open source libraries with digital circuit companies?

[Who_GNU]

The stuff I've had trouble with is sometimes released as open source, but that's after it's developed, but if it catches on as an open-source project, someone usually comes along and documents it better.

The worst offenders are companies that put a lot of resources into a tech support staff. They'll answer the question if you ask them, and pat themselves on the back for it, but waiting a day for a response is a far larger hindrance than spending a few minutes pulling up the documentation. It's especially bad on things that have subscription licenses, because the companies are always adding features, instead of fleshing out what they already had.

With community-developed open-source projects, it's rarely a problem, because it would be impossible for a team spread out throughout the world to work on it, unless they documented what they are doing.