Docs update migration guide 784

[JuLeeAtPlanet]

Related Issue(s):

Closes #784

Proposed Changes:

For inclusion in changelog (if applicable):

n/a

Not intended for changelog:

1. Documentation now includes upgrading from v1 to v1

Diff of User Interface

n/a

PR Checklist:

• This PR is as small and focused as possible
• [] If this PR includes proposed changes for inclusion in the changelog, the title of this PR summarizes those changes and is ready for inclusion in the Changelog.
• [] I have updated docstrings for function changes and docs in the 'docs' folder for user interface / behavior changes
• This PR does not break any examples or I have updated them

(Optional) @mentions for Notifications:
@cholmes

[jreiberkyle]

looks amazing Julee! Suggested a few changes to reflect the current api

[cholmes]

Looks good! There are a few things I'd consider adding, but all of them could come later, so marking this as approved so we can get this in. Happy to help ticket my suggestions if they sound good and we'd do them later.

• Advantages of upgrading - would be good to somewhere articulate what you 'gain' from upgrading, why this is a win. Particularly the bulk requests you can do with async, and the great traffic shaping to maximally utilize our API's. I think @jreiberkyle is planning a blog post on this, so we could just link out to that from here. Or could try to explain in a line or two.
• Additional functionality - this is related to the above, but potentially slightly different. One big one is support for Subscriptions API. We probably should also mention that basemaps and analytics aren't yet supported, so we don't have an 'upgrade path' for those and recommend sticking with v1. But I'm also wondering if we have like nicer helper functions? And like orders says 'orders api capabilities in v1 were quite primitive' - we could explain more of what v2 can help with, that are beyond 'primitive'.
• Links to more async info. Perhaps we even work towards a dedicated section somewhere on async, since we know it's the trickiest aspect. Where we link to some relevant tutorials on async in general, and also link to our examples. We could at least link to the few examples / notebooks we have that show a few different async examples.

Again, this more than satisfies the core need to point people on v1 at a clear upgrade guide, and these are all 'nice to have', and may well better belong in other documents.