We have Googling and trial&error because documentation of APIs is universally deficient.
I just spent two days trying to figure out why my OpenGL 3.2 context would not initialize on Linux. In the end I found it was because I was not using a private colormap. It doesn't make any kind of sense to me, even now, and even knowing what to look for I wasn't able to find any kind of warning in what is laughably called a "manual" (it sure looks like a quick list of function calls without any structure and barely any explanation to me, but YMMV).
How many times do we have to see this:
int CreateContext (int, void*)
"this function creates a context. The first parameter is flags. The second is used to pass additional information."
and are left wondering:
- what _is_ a 'context', what do I need one for, and what is its lifetime?
- what flags can I pass? What do they do, _in detail_?
- what "additional information" can I pass? Is it mandatory? Is it flag-dependent? What structure should it have?
- can there be errors? How do I see them? How do I decode them into something human-readable?
- if I delete the context, will it take any associated items with it, or do I need to free those manually?
- what sort of thread-safety can I expect?
The problem is not skill level, although it certainly helps to be equipped with knowledge of other APIs and the right level of paranoia. It is, for a very large part, badly designed and even badlier documented APIs. And it really doesn't matter where it comes from, amateurs or pros, open source or closed, it's all painfully bad. The best you can usually hope for is a list of function calls, but almost never any sense of how it hangs together, good explanations of parameters and return codes, and let's not even start about thread safety...
As an example of good documentation, I'd like to point out Postgres. These guys really work hard on documentation, and it shines as a result. MSDN, assuming you can find what you were looking for to begin with, is not bad either. And on the other end of the scale we have things like OpenSSL, where I believe lack of documentation is in fact part of their business model. That alone should be reason to avoid it...