Guide to using the new API

The raw APIdoc is insufficient for people to understand how the new API is supposed to be used, or how to port from the old API to the new one.

First draft/start of a guide-ish document for that, should serve as both an explanation of the new API and help for getting up-to-date between the old and the new API.

Want reviews from @rco-odoo @tde-banana-odoo @rim-odoo @nbessi @mart-e 
* is any important note missing? (the guide is not supposed to be exhaustive/complete)
* is anything probably unnecessary for a guide?
* errors?
* other comments?

Not sure how to say that it can be called on an empty recordset or anything, it does not use the recordset it's called on (as opposed to `read` or `write`)