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?

The one bothersome bit is, depending on `__ior__` being implemented and how it's implemented `a |= b` could either modify `a` or replace it with a "new" `a`. So `|=` may or may not be sugar for `a = a | b` (same for `a += b` wrt `a = a + b`).