v3 docs: Add "Resource Summaries" section to upgrade guide

This is just the first pass at this section. I think we can add more.
The goal is to help clients understand why we got rid of most summary
endpoints and how they can achieve similar goals in V3.

Authored-by: Reid Mitchell <rmitchell@pivotal.io>

Author: reidmit

docs/v3/source/includes/upgrade_guide/conceptual_changes/_resource_summaries.md

@@ -0,0 +1,21 @@
+### Resource Summaries
+
+V2 provided several endpoints that returned rolled-up summaries (e.g.
+`/v2/spaces/:guid/summary` for a space summary, or
+`/v2/organizations/:guid/summary` for an organization summary). These endpoints
+have been largely removed from V3 because they were expensive for Cloud
+Controller to compute and because they often returned more information than
+clients actually needed. They were convenient, so it was easy for clients to
+rely on them even when they only needed a few pieces of information.
+
+In V3, to enable better API performance overall, these usage patterns are
+deliberately disallowed. Instead, clients are encouraged to think more carefully
+about which information they really need and to fetch that information with
+multiple API calls and/or by making use of the [`include`
+parameter](#including-associated-resources) on certain endpoints.
+
+#### Usage summary endpoints
+
+There are still a couple of endpoints in V3 that provide a basic summary of
+instance and memory usage. See the [org summary](#get-usage-summary) and
+[platform summary](#get-platform-usage-summary) endpoints.

docs/v3/source/index.md

@@ -372,6 +372,7 @@ includes:
   - upgrade_guide/conceptual_changes/errors
   - upgrade_guide/conceptual_changes/filtering
   - upgrade_guide/conceptual_changes/including_associated_resources
+  - upgrade_guide/conceptual_changes/resource_summaries
   - upgrade_guide/new_concepts/header
   - upgrade_guide/new_concepts/actions
   - upgrade_guide/new_concepts/links