From e1ba31ab5fd58533f3bc190ad773ffd8ad6379f7 Mon Sep 17 00:00:00 2001
From: Marc Garreau <marcdgarreau@gmail.com>
Date: Fri, 12 Jun 2020 17:39:30 -0600
Subject: [PATCH 1/2] add context to index.rst and docs categories

---
 docs/index.rst      | 64 +++++++++++++++++++++++++++++++++------------
 docs/quickstart.rst |  2 ++
 2 files changed, 50 insertions(+), 16 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 750d7ac3f3..03ba0f65a9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,32 +1,63 @@
-Web3.py
-=======
+Introduction
+============
 
-Web3.py is a python library for interacting with Ethereum.  Its API is derived
-from the `Web3.js`_ Javascript API and should be familiar to anyone who has
-used ``web3.js``.
+Web3.py is a Python library for interacting with Ethereum.
 
+It's commonly found in `decentralized apps (dapps)`_ to help with
+sending transactions, interacting with smart contracts, reading
+block data, and a variety of other use cases.
 
-Contents
---------
+The original API was derived from the `Web3.js`_ Javascript API,
+but has since evolved toward the needs and creature comforts of
+Python developers.
+
+Getting Started
+---------------
+
+Your next steps depend on where you're standing:
+
+- Unfamiliar with Ethereum? `ethereum.org`_
+- Looking for Ethereum Python tutorials? `ethereum.org/python`_
+- Ready to code? :ref:`quickstart`
+- Need help debugging? `StackExchange`_
+- Want to chat? `Gitter`_
+
+Table of Contents
+-----------------
 
 .. toctree::
     :maxdepth: 1
+    :caption: Intro
 
     quickstart
     overview
+    releases
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Guides
+
     node
     providers
     examples
     troubleshooting
-    v5_migration
-    v4_migration
+    web3.eth.account
     filters
     contracts
-    ens_overview
     middleware
+    internals
+    abi_types
+    ethpm
+    ens_overview
+    v5_migration
+    v4_migration
+
+.. toctree::
+    :maxdepth: 1
+    :caption: API
+
     web3.main
     web3.eth
-    web3.eth.account
     web3.pm
     web3.net
     web3.miner
@@ -34,10 +65,6 @@ Contents
     web3.parity
     gas_price
     ens
-    ethpm
-    internals
-    abi_types
-    releases
 
 Indices and tables
 ------------------
@@ -47,4 +74,9 @@ Indices and tables
 * :ref:`search`
 
 
-.. _Web3.js: https://github.com/ethereum/wiki/wiki/JavaScript-API
+.. _decentralized apps (dapps): https://ethereum.org/dapps/
+.. _Web3.js: https://web3js.readthedocs.io/
+.. _ethereum.org: https://ethereum.org/what-is-ethereum/
+.. _ethereum.org/python: https://ethereum.org/python/
+.. _StackExchange: https://ethereum.stackexchange.com/questions/tagged/web3.py
+.. _Gitter: https://gitter.im/ethereum/web3.py
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 8860f6f244..9fdc8e8fe7 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -1,3 +1,5 @@
+.. _quickstart:
+
 Quickstart
 ==========
 

From 9f8aab9bb1d1e720b25966cdc5aa44b943a4fd04 Mon Sep 17 00:00:00 2001
From: Marc Garreau <marcdgarreau@gmail.com>
Date: Mon, 15 Jun 2020 10:50:35 -0600
Subject: [PATCH 2/2] add newsfragment

---
 newsfragments/1671.doc.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 newsfragments/1671.doc.rst

diff --git a/newsfragments/1671.doc.rst b/newsfragments/1671.doc.rst
new file mode 100644
index 0000000000..2367a282a5
--- /dev/null
+++ b/newsfragments/1671.doc.rst
@@ -0,0 +1 @@
+Breaks up links into three categories (Intro, Guides, and API) and adds content to the index page: a lib introduction and some "Getting Started" links.