From 7c0674641b28cd73fc0eea2ba91c1e03bf99e3fc Mon Sep 17 00:00:00 2001
From: Alex Gaynor <alex.gaynor@gmail.com>
Date: Mon, 16 Dec 2013 10:11:00 -0800
Subject: Rework the index to give people a better lay of the land

---
 docs/index.rst | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/index.rst b/docs/index.rst
index 776c9d37..dd20a4a4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -32,9 +32,24 @@ existing libraries:
 * Poor introspectability, and thus poor testability.
 * Extremely error prone APIs, and bad defaults.
 
+Layout
+------
 
-Contents
---------
+``cryptography`` is broadly divided into two levels. One with safe
+cryptographic recipes, "cryptography for humans" if you will. These are safe
+and easy to use and don't require developers to make many decisions.
+
+The other level is low-level cryptographic primitives. These are often
+dangerous and can be used incorrectly. They require making decisions and having
+an in-depth knowledge of the cryptographic concepts at work. Because of the
+potential danger in working at this level, this is referred to as the "hazmat"
+layer.
+
+We recommend using the recipes layer whenever possible, and falling back to the
+hazmat layer only when necessary.
+
+The recipes layer
+~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 2
@@ -42,15 +57,23 @@ Contents
     architecture
     exceptions
     glossary
-    contributing
-    security
-    community
 
 Hazardous Materials
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 2
 
     hazmat/primitives/index
     hazmat/backends/index
+
+
+The ``cryptography`` open source project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+    :maxdepth: 2
+
+    contributing
+    security
+    community
-- 
cgit v1.2.3