The problem with documentation is that they're generally written by the developers themselves and are burdened by the curse of knowledge. A lot of bad documenta

The problem with documentation is that they're generally written by the developers themselves and are burdened by the curse of knowledge. A lot of bad documentation I've dealt with is often riddled with acronyms and a priori knowledge of underlying systems and external dependencies. I think a good approach is to hire junior developers/interns and just ask them to build stuff off your API from scratch and carefully record their pain points, questions, etc. As a bonus, the stuff they build can also later be used as working "best practice" examples -- assuming you get your developers to code review them. I say junior developers because they're a good knowledge baseline to aim for and are probably not "contaminated" with a priori knowledge of your system or similar alternatives.