The sweet spot, I think, is a nice "getting started" guide along with an discoverable API design. The guide gives prospective users an idea what it's like to use the library, and the discoverableness means they'll be able to figure out the more complex stuff without precarious trial-and-error or obscure doc spelunking.