When people download your API, they don’t care about your API. They care about what it can do for them in the context of getting their game done. This means that they don’t want to have to read or change the source to compile. They don’t want to have to search Google for a single minute to get around compiler or linker errors. They don’t even want to compile the binaries. They want to add a few header files, a binary, and compile straight away in any configuration. If any special settings are necessary, they want those settings to be immediately and obviously apparent available in the manual. The settings should be as clear as possible, with screenshots and exact names when appropriate. It should work the first time and by work I mean do what the user thinks it should do, not what you think it should do. Lastly, it should not force them to change a single line of code in their program. They should add your code, not modify their code to fit the way you think code should be designed.
You think people don’t mind checking the source? In RakNet I’ve had people bitterly report problems that could have been resolved in 30 seconds by looking at the source. Let me be clear: When people complain about problems in MY api you know it’s obscenely simple stuff because I hide the complexity. You, unless you are the author of Irrlicht, probably do not. I’ve had people complain about not being able to compile in Dev CPP. I, who had never used it in my life, was able to compile my library in 10 minutes. From that point on I included a Dev CPP library in future builds. When I forget to update the library, people complain although the mistakes are trivial to fix, such as a file that no longer exists. People DO NOT like to spend time resolving problems getting your API to work, nor should they.
Given the kind of user I just described, imagine giving one of them Open AL and telling them to use it in source code format. There is no function level API documentation. There are no compiler instructions. It won’t compile unless you include the exact specific files, with no way to know which files they are other than trial and error. You then have to change the code in 3 places, trace through the source to resolve a crash, set a preprocessor definition, and manually call DLLMain code, either by modifying the source or writing a new file to do it. Lastly, you have to resolve a DirectX GUID dependency by including dxguid.lib, something not clear by from the errors that come up.
Don’t even bother writing an API if you are not going to make it user-friendly. If you’re going to cost your end-user time to use your library, they will just use something else.