From 2efc21976ad1a384150660cdd98062090c8d1a15 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 3 Mar 2022 10:33:14 -0500
Subject: [PATCH] quick doc adjustments

tweet thread:  https://twitter.com/zzzeek/status/1499397255089909762

Change-Id: I5556ef707c2285e7b64c91ae5c58af52efcf4770
(cherry picked from commit f68a51c549754637bd59213101025f1ee63e4865)
---
 doc/build/index.rst | 52 ++++++++++++++++++++++++++++++++-------------
 doc/build/intro.rst |  6 ++++++
 2 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/doc/build/index.rst b/doc/build/index.rst
index 35005872f4..d39f1217a7 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -16,16 +16,11 @@ SQLAlchemy Documentation
 
   .. container::
 
-    A high level view and getting set up.
+    New to SQLAlchemy?   Start here:
 
-    :doc:`Overview <intro>` |
-    :ref:`Installation Guide <installation>` |
-    :doc:`Frequently Asked Questions <faq/index>` |
-    :doc:`Migration from 1.3 <changelog/migration_14>` |
-    :doc:`Glossary <glossary>` |
-    :doc:`Error Messages <errors>` |
-    :doc:`Changelog catalog <changelog/index>`
+    * **For Python Beginners:** :ref:`Installation Guide <installation>` - basic guidance on installing with pip and similar
 
+    * **For Python Veterans:** :doc:`SQLAlchemy Overview <intro>` - brief architectural overview
 
 .. container:: left_right_container
 
@@ -37,20 +32,17 @@ SQLAlchemy Documentation
 
   .. container::
 
-    **SQLAlchemy 1.4 / 2.0 Transitional**
+    **SQLAlchemy 1.4 / 2.0**
 
     SQLAlchemy 2.0 is functionally available as part of SQLAlchemy 1.4, and integrates
     Core and ORM working styles more closely than ever.   The new tutorial introduces
-    both concepts in parallel.  New users and those starting new projects should start here!
-
-    * :doc:`/tutorial/index` - SQLAlchemy 2.0's main tutorial
-
-    * :doc:`Migrating to SQLAlchemy 2.0 <changelog/migration_20>` - Complete background on migrating from 1.3 or 1.4 to 2.0
+    both concepts in parallel.
 
+    * **For all users:** :doc:`/tutorial/index` - The new SQLAlchemy 1.4/2.0 Tutorial
 
   .. container::
 
-    **SQLAlchemy 1.x Releases**
+    **Legacy SQLAlchemy 1.x Tutorials**
 
     The 1.x Object Relational Tutorial and Core Tutorial are the legacy tutorials
     that should be consulted for existing SQLAlchemy codebases.
@@ -60,6 +52,21 @@ SQLAlchemy Documentation
     * :doc:`core/tutorial`
 
 
+.. container:: left_right_container
+
+  .. container:: leftmost
+
+      .. rst-class:: h2
+
+        Migration Notes
+
+  .. container::
+
+    * :doc:`Migration from 1.3 <changelog/migration_14>` - Migration notes for SQLAlchemy Version 1.4
+    * :doc:`SQLAlchemy 2.0 Preview <changelog/migration_20>` - Background on preparing a SQLAlchemy 1.4 application for SQLAlchemy 2.0
+    * :doc:`Changelog catalog <changelog/index>` - Detailed changelogs for all SQLAlchemy Versions
+
+
 .. container:: left_right_container
 
   .. container:: leftmost
@@ -150,3 +157,18 @@ SQLAlchemy Documentation
 
       :doc:`More Dialects ... <dialects/index>`
 
+.. container:: left_right_container
+
+  .. container:: leftmost
+
+      .. rst-class:: h2
+
+        Supplementary
+
+  .. container::
+
+    * :doc:`Frequently Asked Questions <faq/index>` - A collection of common problems and solutions
+    * :doc:`Glossary <glossary>` - Terms used in SQLAlchemy's documentation
+    * :doc:`Error Message Guide <errors>` - Explainations of many SQLAlchemy Errors
+    * :doc:`Complete table of of contents <contents>`
+    * :doc:`Index <index>`
diff --git a/doc/build/intro.rst b/doc/build/intro.rst
index 01e33df034..4f1b64d15b 100644
--- a/doc/build/intro.rst
+++ b/doc/build/intro.rst
@@ -206,6 +206,12 @@ Python prompt like this:
      >>> sqlalchemy.__version__ # doctest: +SKIP
      1.4.0
 
+Next Steps
+----------
+
+With SQLAlchemy installed, new and old users alike can
+:ref:`Proceed to the SQLAlchemy Tutorial <unified_tutorial>`.
+
 .. _migration:
 
 1.3 to 1.4 Migration
-- 
2.47.2