This needs to add a caveat. Current users will almost certainly prefer the older API. Newer ones are more likely to be hesitant about dealing with a tangled mes

This needs to add a caveat. Current users will almost certainly prefer the older API. Newer ones are more likely to be hesitant about dealing with a tangled mess. Also, most documentation of APIs is nowhere near good, so intuition matters a lot.