[ADD] doc: tentative guide to the new API

Turns out most people have a hard time understanding the new API from no
documentation (or just the API documentation) or just the opendays slides
things (not to mention things have changed since).

Tries to lay down some basics and porting info.