> It's called being an effective communicator. […] bring the audience along […] Readers shouldn't have to perform exegesis

He's optimising for communicating with his peers: scientists and academic researchers.

If you find this communication hard to digest, then chances are you are not part of the intended audience. It is then mostly pointless to complain or try to change his wording.

You can buy books from other people who deliberately target developers.

• https://oreilly.com/catalog/9780596529260 • https://oreilly.com/catalog/9780596801694 • https://restinpractice.com/ • http://www.designinghypermediaapis.com/

I recommend this physical book: 'RESTful Web Services Cookbook'. It walks you though the rationale behind HTTP APIs and progressively using more and more of HTTP's features to build a sophisticated but elegant API.

[1] http://shop.oreilly.com/product/9780596801694.do

Anyone know if the RESTful Web Services book is any good, or know of a good resource? http://oreilly.com/catalog/9780596801687/