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?

That is definitely a weakness, and I should probably add a warning about it.

In most cases it will not contain duplicates but it can if it's seeded with duplicates (in a browse) or if two recordsets with duplicates are concatenated (with `+`, `|` will remove duplicates). The lack of native orderedsets and the current frequency of re-browsing (because of context switches between new and old apis) make building dedup in a big performance issue though.