docs: add recommendation to use v2.x and static discovery artifacts

README.md

@@ -16,10 +16,22 @@ where possible, for new code development. For more information, please visit
 [Client Libraries Explained](https://cloud.google.com/apis/docs/client-libraries-explained).
 
 ## Version 2.0 Release
-The 2.0 release of `google-api-python-client` is a significant upgrade compared
-to v1. Please see the [Migration Guide](https://github.com/googleapis/google-api-python-client/blob/master/UPGRADING.md) for more information.
-As a result of caching the discovery documents, the size of this package is at
-least 50 MB larger compared to the previous version.
+The 2.0 release of `google-api-python-client` includes a substantial reliability 
+improvement, compared with 1.x, as discovery documents are now cached in the library 
+rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.
+
+Only python 3.6 and newer is supported. If you are not able to upgrade python, then
+please continue to use version 1.x as we will continue supporting python 2.7+ in
+[v1](https://github.com/googleapis/google-api-python-client/tree/v1).
+
+Discovery documents will no longer be retrieved dynamically when
+you call  `discovery.build()`. The discovery documents will instead be retrieved
+from the client library directly. New versions of this library are released weekly.
+As a result of caching the discovery documents, the size of this package is at least 
+50 MB larger compared to the previous version. 
+
+Please see the [Migration Guide](https://github.com/googleapis/google-api-python-client/blob/master/UPGRADING.md)
+for more information.
 
 ## Documentation
 

UPGRADING.md

@@ -1,35 +1,34 @@
 # 2.0.0 Migration Guide
 
-The 2.0 release of `google-api-python-client` is a significant upgrade as only
-python 3.6 and newer is supported. If you are not able to upgrade python, then
+The 2.0 release of `google-api-python-client` includes a substantial reliability 
+improvement, compared with 1.x, as discovery documents are now cached in the library 
+rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.
+
+Only python 3.6 and newer is supported. If you are not able to upgrade python, then
 please continue to use version 1.x as we will continue supporting python 2.7+ in
 [v1](https://github.com/googleapis/google-api-python-client/tree/v1).
 
-In addition, discovery documents will no longer be retrieved dynamically when
+Discovery documents will no longer be retrieved dynamically when
 you call  `discovery.build()`. The discovery documents will instead be retrieved
-from the client library directly. As a result of caching the discovery
-documents, the size of this package is at least 50 MB larger compared to the
-previous version.
+from the client library directly. New versions of this library are released weekly.
+As a result of caching the discovery documents, the size of this package is at least 
+50 MB larger compared to the previous version. 
 
 
 For users of public APIs
 ------------------------
 Existing code written for earlier versions of this library will not require
-updating. We believe this new default behaviour will provide a more predictable
-experience for users. If always using the latest version of a service definition
-is more important than reliability, users should set the `static_discovery`
-argument of `discovery.build()` to `False` to retrieve the service definition
-from the internet.
+updating. 
 
 For users of private APIs
 -------------------------
-If the discovery document requires an authentication key to access it, the
+If the discovery document requires an authentication key to access it then the
 discovery document is private and it will not be shipped with the library.
 Only discovery documents listed in [this public directory](https://www.googleapis.com/discovery/v1/apis/)
 are included in the library. Users of private APIs should set the
 `static_discovery` argument of `discovery.build()` to `False` to continue to
 retrieve the service definition from the internet. As of version 2.1.0,
-for backwards compatability with version 1.x, if `static_discovery` is not
+for backwards compatibility with version 1.x, if `static_discovery` is not
 specified, the default value for `static_discovery` will be `True` when
 the `discoveryServiceUrl` argument of `discovery.build()` is provided.
 
@@ -45,13 +44,12 @@ to use version 2.0.0.
 ## Method Calls
 
 **Note**: Existing code written for earlier versions of this library will not
-require updating. You should only update your code if always using the latest
-version of a service definition is more important than reliability or if you
-are using an API which does not have a public discovery document.
+require updating. You should only update your code if you are using an API 
+which does not have a public discovery document.
 
 > **WARNING**: Breaking change
 
-The 2.0.0 release no longer retrieves discovery documents dynamically on each
+The 2.0 release no longer retrieves discovery documents dynamically on each
 call to `discovery.build()`. Instead, discovery documents are retrieved from
 the client library itself.
 
@@ -78,7 +76,7 @@ from googleapiclient.discovery import build
 with build('drive', 'v3') as service:
     # ...
 
-# Retrieve discovery artifacts from the internet
+# Retrieve discovery artifacts from the internet for a private API
 with build('drive', 'v3', static_discovery=False) as service:
     # ...
 ```