planet-client-python
planet-client-python copied to clipboard
Improve documentation about upgrading with additional information
Per @cholmes in discussion of Beta release of Upgrade from Version 1 to Version 2 content:
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.
Describe alternatives you've considered Nice-to-have, per PM