Clarify use-case and docs structure (#648)

docs/index.rst

@@ -2,11 +2,22 @@
 The PyData Sphinx Theme
 =======================
 
-This is a simple, Bootstrap-based Sphinx theme from the PyData community. This
-site is a guide for using the theme, and a demo for how it looks with various
+A clean, Bootstrap-based Sphinx theme from the PyData community.
+This theme is designed for more complex documentation that breaks into natural sub-sections.
+
+It puts all top-level pages in your ``toctree`` into the header navigation bar.
+The sidebar will be populated with second-level pages when a top-level page is active.
+This allows you to group your documentation into sub-sections without cluttering the sidebar.
+
+.. seealso::
+
+   If you are looking for a Sphinx theme that puts all of its sub-pages in the sidebar, the `Sphinx Book Theme <https://sphinx-book-theme.readthedocs.io/>`_ has a similar look and feel, and `Furo <https://pradyunsg.me/furo/quickstart/>`_ is another excellent choice.
+
+This site is a guide for using the theme, and a demonstration for how it looks with various
 elements.
 
-Other sites that are using this theme:
+Sites that use this theme
+=========================
 
 .. SORTED ALPHABETICALLY
 

docs/user_guide/index.rst

@@ -2,6 +2,16 @@
 User Guide
 ==========
 
+The user guide describes how to use and customize this theme.
+
+How the theme is structured
+===========================
+
+This theme converts all **top-level toctree items** into links in the header navigation bar.
+The sidebar will have no navigation links until one of these top-level links is active (e.g., if you are on a sub-page of a top-level link).
+Once one of the top-level links is active, the sidebar will be populated with a list of pages that are underneath the top-level page.
+
+For example, see the links in the sidebar for the other pages in this section.
 
 .. toctree::
    :maxdepth: 2