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?

Is there really a risk of confusion?