Yes, the documentation could be better. Most endpoints are easy to understand by actual players of the game but some are indeed more complex.
Well, that is why we have an API community. Do you have any particular question about the endpoints you would like to ask ?
You can also try the Blizzard API Community Discord Server there is always someone willing to help.