Merge pull request #593 from alex/better-readme

Fixed #576 -- improve the readme

2 files changed, 20 insertions, 7 deletions

diff --git a/README.rst b/README.rst
index 0c59136e..b7d60cbd 100644
--- a/README.rst
+++ b/README.rst
@@ -9,14 +9,28 @@ Cryptography
 
 
 ``cryptography`` is a package designed to expose cryptographic recipes and
-primitives to Python developers.
-
-It is currently in early development and isn't recommended for general usage
-yet. It targets Python 2.6-2.7, Python 3.2+, and PyPy.
+primitives to Python developers.  Our goal is for it to be your "cryptographic
+standard library". It supports Python 2.6-2.7, Python 3.2+, and PyPy.
+
+``cryptography`` includes both high level recipes, and low level interfaces to
+common cryptographic algorithms such as symmetric ciphers, message digests and
+key derivation functions. For example, to encrypt something with
+``cryptography``'s high level symmetric encryption recipe:
+
+.. code-block:: pycon
+
+    >>> from cryptography.fernet import Fernet
+    >>> # Put this somewhere safe!
+    >>> key = Fernet.generate_key()
+    >>> f = Fernet(key)
+    >>> token = f.encrypt(b"A really secret message. Not for prying eyes.")
+    >>> token
+    '...'
+    >>> f.decrypt(token)
+    'A really secret message. Not for prying eyes.'
 
 You can find more information in the `documentation`_.
 
-
 Discussion
 ~~~~~~~~~~
 
diff --git a/docs/index.rst b/docs/index.rst
index 9114b895..19feb603 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,8 +2,7 @@ Welcome to ``cryptography``
 ===========================
 
 ``cryptography`` is a Python library which exposes cryptographic recipes and
-primitives. We hope it'll be your one-stop-shop for all your cryptographic
-needs in Python.
+primitives. Our goal is for it to be your "cryptographic standard library".
 
 Installation
 ------------