Agree completely. Another good example is these guys https://gocardless.com/docs/

If I'm looking at an external service/API for use in one of our products the first thing I look for from a technical perspective (is this priced right) is good code samples of API usage, then I look take a look a whistlestop tour through the docs (mostly to get an idea of quality and completeness).

At that point I might whip up a simple project against their API (if they make it easy to do and without having to pay...) and if I like it then I'll buy, Another good example I ran into recently was Nexmo, very easy to use and good docs.

...so you're saying, no one will read the documentation, because they'll all be looking at the documentation?

You've lost me I'm afraid.

(unless you're saying that api documentation, specifically, isn't very useful compared to say, examples, in which case, you're agreeing with me, because useless api documentation is what you get when you run a documentation tool over a code base without annotations...)

> ...so you're saying, no one will read the documentation, because they'll all be looking at the documentation?

I think he means that devs won't be reading documentation like a book, chapter by chapter, trying to comprehend what API does, but instead they will look at tutorials and code snippets, and enter your documentation at random points via Google / StackOverflow links, mostly in cases when something is not working.