Update docs to add note about back-compat

Also add some very basic upgrading notes for the early adopters.

I also updated the tutorial to use client objects.

cc @danielgtaylor @kyleknap 
Unfortunately, I'm not really sure where to point them at.  We aren't currently generating doc strings for client methods (yet).  Any suggestions on where to point them?