(DOCSP-30173): Proactive performance insights (#525)

* (DOCSP-30173): Proactive performance insights

* edits

* edits

* fix broken ref

* fix ref link

* add blurb for automatically enabled

* adjust table heading

* address Julia's feedback

* minimalism

* fix toc

* address Julia's feedback

* intro sentence

* wording

* wording tweak

* internal review edit

* add ref to release notes

* wording

Author: jeff-allen-mongo

source/manage-data.txt

@@ -31,6 +31,10 @@ Interact with Your Data
   Learn how to analyze your data schema and shape of the fields in a
   particular collection.
 
+:ref:`compass-performance-insights`
+  Learn how to analyze your data schema and shape of the fields in a
+  particular collection.
+
 :doc:`/validation`
   Learn how to ensure that all documents in a collection
   follow a defined set of rules.
@@ -52,6 +56,7 @@ Interact with Your Data
    /query/filter
    /indexes
    /schema
+   /manage-data/performance-insights
    /validation
    /sampling
    /in-use-encryption-tutorial

source/manage-data/performance-insights.txt

@@ -0,0 +1,85 @@
+.. _compass-performance-insights:
+
+====================
+Performance Insights
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+When |compass| determines that your schema or queries can be improved,
+it displays a performance insight. Performance insights show ways to
+improve your schema and data modeling practices. Use performance
+insights to learn best schema design practices and improve application
+performance.
+
+Use Cases
+---------
+
+Performance insights are best followed early in your application
+development process. Starting your application with good data modeling
+practices helps prevent schema and performance issues as your
+application grows.
+
+Although |compass-short| provides performance insights at any stage of
+development, it can be difficult to make schema modifications in
+large-scale schemas that are used in production.
+
+Before you modify your schema based on performance insights, ensure that
+the suggestion makes sense for your application. For example, if
+|compass-short| suggests creating an index, make sure that index
+supports queries that are run frequently.
+
+Behavior
+--------
+
+Performance insights are enabled automatically.
+
+Performance insights are generic, and do not use properties specific to
+your schema such as database or collection names.
+
+|compass-short| shows performance insights in the following scenarios:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 10
+
+   * - Scenario
+     - Performance insight
+   
+   * - You run a query or aggregation without an index.
+     - Add an index to support the operation.
+
+   * - You run an aggregation pipeline that uses a :pipeline:`$lookup`
+       stage.
+     - Embed related data to avoid the need for a ``$lookup`` operation.
+
+   * - You run a :query:`$text` or :query:`$regex` query.
+     - If possible, use :atlas:`Atlas Search </atlas-search>` to improve
+       performance for text search queries.
+
+   * - Your database contains too many collections.
+     - Reduce the number of collections.
+
+   * - Your documents contain an array field with too many elements.
+     - Avoid unbounded arrays.
+
+   * - The data size of individual documents is too large.
+     - Break up large documents into separate collections.
+
+   * - Your collection contains too many indexes.
+     - Review your indexes and remove any that are unnecessary.
+
+Learn More
+----------
+
+- To learn more about data modeling in MongoDB, see
+  :ref:`manual-data-modeling-intro`.
+
+- To learn how to create effective indexes for your application, see
+  :manual:`Indexing Strategies </applications/indexes>`.

source/release-notes.txt

@@ -18,9 +18,10 @@ Release Notes
 
 New features:
 
-- Enable proactive performance insights by default. Proactive
-  performance insights analyze your queries and suggest ways to improve
-  performance. (:issue:`COMPASS-7000`)
+- Enable :ref:`proactive performance insights
+  <compass-performance-insights>` by default. Proactive performance
+  insights analyze your queries and suggest ways to improve performance.
+  (:issue:`COMPASS-7000`)
 
 Bug Fixes:
 

source/schema.txt

@@ -12,9 +12,6 @@ Analyze Your Data Schema
    :depth: 1
    :class: singlecol
 
-Overview
---------
-
 The :guilabel:`Schema` tab provides an overview of the data type
 and shape of the fields in a particular collection. Databases
 and collections are visible in the left-side navigation.