(DOCSP-7838): Making querying documents more task-centric (ToC Refactor) (#206)

* (DOCSP-7838): Making querying documents more task-centric

* Updates per Gilberto's review

Author: jeff-allen-mongo

config/sphinx_local.yaml

@@ -9,6 +9,7 @@ theme:
   google_analytics: 'UA-7301842-8'
   nav_excluded:
     - /
+    - /manage-data
     - /troubleshooting
     - /troubleshooting/connection-errors
 sidebars:

source/collections.txt

@@ -1,8 +1,8 @@
 .. _collection-tab:
 
-=====================
-Collections and Views
-=====================
+===========
+Collections
+===========
 
 .. default-domain:: mongodb
 
@@ -12,32 +12,23 @@ Collections and Views
    :depth: 1
    :class: singlecol
 
-.. _collections-screen:
+A collection is a grouping of MongoDB
+:ref:`documents <compass-documents>`. Documents within a collection can
+have different fields. A collection is the equivalent of a
+table in a relational database system. A collection exists within a
+single :ref:`database <database-tab>`
+
+.. _collections-screen-collections:
 
 Collections Screen
 ------------------
 
-The :guilabel:`Collections` screen lists the existing
-:ref:`collections <compass-collections>` and
-:ref:`views <compass-views>` in the selected database. Each
-list item includes the name and other general information for
-the specific collection/view.
-
-To access the :guilabel:`Collections` screen for a database, from the
-:doc:`Databases screen </databases>` either:
-
-- Click a :guilabel:`Database Name` in the main :guilabel:`Databases`
-  view, or
-
-- Click a database in the left navigation.
-
-.. figure:: /images/compass/select-database.png
-   :figwidth: 750px
+.. include:: /includes/fact-collections-screen.rst
 
 .. _compass-collections:
 
-Collections
-~~~~~~~~~~~
+Collection Information
+~~~~~~~~~~~~~~~~~~~~~~
 
 The :guilabel:`Collections` screen displays the following
 information for each collection in the selected database:
@@ -52,37 +43,6 @@ information for each collection in the selected database:
   collection. Hover over a :guilabel:`Collation` banner to view
   the properties for that collection.
 
-.. _compass-views:
-
-Views
-~~~~~
-
-Views are read-only results of an aggregation run against a collection. 
-The :guilabel:`Collections` screen displays the following information
-for each view in the selected database:
-
-- View name
-- Collection from which the view was created
-- Total size of all documents in the view
-- Total size of all indexes on the collection
-
-|compass-short| explicitly marks views in the left navigation with
-a unique icon:
-
-.. figure:: /images/compass/view-icon.png
-   :scale: 50%
-   :alt: View icon
-
-For more information on views, see :ref:`view-details`.
-
-Limitations
------------
-
-- .. include:: /includes/extracts/readonly-not-permitted-collections.rst
-
-- The :guilabel:`Create Collection` button is not available if you are 
-  connected to a :atlas:`Data Lake </data-lake>`.
-
 .. _create-collection:
 
 Create a Collection
@@ -119,34 +79,39 @@ collection details, either:
   :scale: 90%
 
 After you select a collection, |compass-short| shows you that
-collection's :doc:`Documents tab </documents>`. |compass-short| provides the following
-collection information and functionality in the detailed view:
+collection's :doc:`Documents tab </documents>`. |compass-short| provides
+the following collection information and functionality in the detailed
+view:
 
 - :doc:`/documents`
 
 - :doc:`Import and Export Data </import-export/>` to / from the collection
-  
-  Importing data is not available if you are connected to 
-  a :atlas:`Data Lake </data-lake>`
 
 - :ref:`compass-agg-builder`
 
-- :doc:`Schema Analysis </schema>` 
-  
-  Not Available in Compass Community Edition
+- :doc:`Schema Analysis </schema>`
+
+- :doc:`/query-plan`
+
+- :doc:`/indexes`
+
+- :doc:`/validation`
 
-- :doc:`/query-plan` 
-  
-  Not Available if you are connected to a :atlas:`Data Lake </data-lake>`
+.. admonition:: Data Lake Limitations
+   :class: note
 
-- :doc:`/indexes` 
-  
-  Not Available if you are connected to a :atlas:`Data Lake </data-lake>`
+   The following functionality is not available if you are connected to
+   a :atlas:`Data Lake </data-lake>`:
 
-- :doc:`/validation` 
-  
-  Not Available in Compass Community Edition or if 
-  you are connected to a :atlas:`Data Lake </data-lake>`
+   - Import data into a collection
+
+   - Schema Analysis
+
+   - View Query Performance
+
+   - Manage Indexes
+
+   - Set Validation Rules for Your Schema
 
 .. _tabbed-view:
 
@@ -158,17 +123,12 @@ open a new tab to view collection details:
 
 .. include:: /includes/steps/open-new-tab.rst
 
-.. class:: hidden
+Limitations
+-----------
 
-   .. toctree::
-      :titlesonly:
+- .. include:: /includes/extracts/readonly-not-permitted-collections.rst
 
-      /query-bar
-      /documents
-      /schema
-      /query-plan
-      /indexes
-      /validation
-      /views
+- The :guilabel:`Create Collection` button is not available if you are 
+  connected to a :atlas:`Data Lake </data-lake>`.
 
 .. |home| unicode:: U+2302

source/databases.txt

@@ -12,6 +12,10 @@ Databases
    :depth: 1
    :class: singlecol
 
+A database is a container for :ref:`collections <collection-tab>`.
+Each database gets its own set of files on the host file system.
+A single MongoDB server typically has multiple databases.
+
 Databases Tab
 -------------
 
@@ -30,14 +34,6 @@ database collections by clicking the desired database in the left-hand navigatio
 You can also :ref:`create <create-database>` or
 :ref:`drop databases <drop-database>` from this view.
 
-Limitations
------------
-
--  .. include:: /includes/extracts/readonly-not-permitted-databases.rst
-
--  Creating databases is not permitted if you are connected to a 
-   :atlas:`Data Lake </data-lake>`.
-
 .. _create-database:
 
 Create a Database
@@ -51,3 +47,11 @@ Drop a Database
 ---------------
 
 .. include:: /includes/steps/delete-database.rst
+
+Limitations
+-----------
+
+-  .. include:: /includes/extracts/readonly-not-permitted-databases.rst
+
+-  Creating databases is not permitted if you are connected to a 
+   :atlas:`Data Lake </data-lake>`.

source/documents.txt

@@ -1,11 +1,14 @@
 .. _compass-documents:
 
-=============
-Documents Tab
-=============
+================
+Manage Documents
+================
 
 .. default-domain:: mongodb
 
+Documents are individual records in a MongoDB :ref:`collection
+<collection-tab>` and are the basic unit of data in MongoDB.
+
 .. _documents-tab:
 
 From the :guilabel:`Documents` tab, you can
@@ -23,13 +26,12 @@ collection or view.
 
    .. include:: /includes/extracts/query-bar-results.rst
 
-From the :doc:`query bar </query-bar>`, you can specify a query to
+From the :ref:`query bar <query-bar>`, you can specify a query to
 filter the displayed documents. Click :guilabel:`Options` to
 specify query options.
 
 .. seealso::
 
-   - :doc:`query-bar`
    - :doc:`/documents/view`
    - :doc:`/documents/insert`
    - :doc:`/documents/modify`

source/export-query-to-language.txt

@@ -27,15 +27,15 @@ Procedure
 #. Select :guilabel:`Export to Language`:
 
    .. figure:: /images/querybar/export-query-to-language-menu-option.png
-      :figwidth: 300px
+      :figwidth: 600px
       :lightbox:
       :alt: Query bar export dropdown menu
 
 #. In the :guilabel:`Export Query To:` dropdown, select your desired
    language:
 
    .. figure:: /images/querybar/export-query-to-language-select.png
-      :figwidth: 300px
+      :figwidth: 600px
       :lightbox:
       :alt: Query bar language select
 

source/includes/fact-collections-screen.rst

@@ -0,0 +1,16 @@
+The :guilabel:`Collections` screen lists the existing
+:ref:`collections <compass-collections>` and
+:ref:`views <compass-views>` in the selected database. Each
+list item includes the name and other general information for
+the collection or view.
+
+To access the :guilabel:`Collections` screen for a database, from the
+:doc:`Databases screen </databases>` either:
+
+- Click a :guilabel:`Database Name` in the main :guilabel:`Databases`
+  view, or
+
+- Click a database in the left navigation.
+
+.. figure:: /images/compass/select-database.png
+   :figwidth: 750px

source/includes/toc-manage-data.yaml

@@ -0,0 +1,37 @@
+file: /databases
+description: |
+  Learn how to create and manage databases in your deployment.
+---
+file: /collections
+description: |
+  Learn how to manage collections in your databases.
+---
+file: /views
+description: |
+  Learn how to manage views in your databases. Views are read-only
+  results of an :ref:`aggregation <compass-agg-builder>` run against
+  a collection.
+---
+file: /documents
+description: |
+  Learn how to manage documents in your collections.
+---
+file: /query/filter
+description: |
+  Learn how to query your data to return data that matches a specified
+  criteria.
+---
+file: /indexes
+description: |
+  Learn how to create indexes to improve query performance.
+---
+file: /schema
+description: |
+  Learn how to analyze your data schema and shape of the fields in a
+  particular collection.
+---
+file: /validation
+description: |
+  Learn how to ensure that all documents in a collection
+  follow a defined set of rules.
+...

source/index.txt

@@ -148,7 +148,8 @@ https://github.com/mongodb-js/compass/.
       /install
       /connect
       /instance
-      /collections
+      /data-concepts
+      /manage-data
       /aggregation-pipeline-builder
       /import-export
       /troubleshooting

source/indexes.txt

@@ -1,8 +1,8 @@
 .. _compass-indexes:
 
-===========
-Indexes Tab
-===========
+==============
+Manage Indexes
+==============
 
 .. default-domain:: mongodb
 
@@ -71,4 +71,3 @@ Drop an Index
 ---------------
 
 .. include:: /includes/steps/drop-index.rst
-

source/instance.txt

@@ -71,5 +71,4 @@ For more information about the :guilabel:`Performance` tab, see
    .. toctree::
       :titlesonly:
 
-      /databases
       /performance