The docs are horrible and often contradictory -- but with enough trial and error most things can be figured out.

The unannounced breaking changes are absolutely inexcusable and screw the people using your platform. It is not a sustainable development plan, you will eventually alienate 'the next Zynga' and all the smaller developers. Please, please, please put some effort into API stability.