Update some user docs

1 files changed, 14 insertions, 17 deletions

diff --git a/README.md b/README.md
index 53c16e2..0430dbc 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/requests-cache?color=blue)](https://pypi.org/project/requests-cache)
 
 ## Summary
-**requests-cache** is a transparent, persistent cache that provides an easy way to get better
+**requests-cache** is a persistent HTTP cache that provides an easy way to get better
 performance with the python [requests](http://python-requests.org) library.
 
 <!-- RTD-IGNORE -->
@@ -23,7 +23,7 @@ Complete project documentation can be found at [requests-cache.readthedocs.io](h
   with a [drop-in replacement](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#sessions)
   for `requests.Session`, or
   [install globally](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#patching)
-  to add caching to all `requests` functions.
+  to add transparent caching to all `requests` functions.
 * 🚀 **Performance:** Get sub-millisecond response times for cached responses. When they expire, you
   still save time with
   [conditional requests](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#conditional-requests).
@@ -31,14 +31,13 @@ Complete project documentation can be found at [requests-cache.readthedocs.io](h
   [storage backends](https://requests-cache.readthedocs.io/en/stable/user_guide/backends.html)
   including SQLite, Redis, MongoDB, and DynamoDB; or save responses as plain JSON files, YAML,
   and more
+* 🕗 **Expiration:** Use
+  [Cache-Control](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#cache-control)
+  and other standard HTTP headers, define your own expiration schedule, keep your cache clutter-free
+  with backends that natively support TTL, or any combination of strategies
 * ⚙️ **Customization:** Works out of the box with zero config, but with a robust set of features for
   configuring and extending the library to suit your needs
-* 🕗 **Expiration:** Keep your cache fresh using
-  [Cache-Control](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#cache-control),
-  eagerly cache everything for long-term storage, use
-  [URL patterns](https://requests-cache.readthedocs.io/en/stable/user_guide/expiration.html#expiration-with-url-patterns)
-  for selective caching, or any combination of strategies
-* ✔️ **Compatibility:** Can be combined with other
+* 🧩 **Compatibility:** Can be combined with other
   [popular libraries based on requests](https://requests-cache.readthedocs.io/en/stable/user_guide/compatibility.html)
 
 ## Quickstart
@@ -77,7 +76,6 @@ With caching, the response will be fetched once, saved to `demo_cache.sqlite`, a
 requests will return the cached response near-instantly.
 
 **Patching:**
-
 If you don't want to manage a session object, or just want to quickly test it out in your
 application without modifying any code, requests-cache can also be installed globally, and all
 requests will be transparently cached:
@@ -89,23 +87,22 @@ requests_cache.install_cache('demo_cache')
 requests.get('http://httpbin.org/delay/1')
 ```
 
-**Configuration:**
-
-A quick example of some of the options available:
+**Settings:**
+The default settings work well for most use cases, but there are plenty of ways to customize
+caching behavior when needed. Here is a quick example of some of the options available:
 ```python
-# fmt: off
 from datetime import timedelta
 from requests_cache import CachedSession
 
 session = CachedSession(
     'demo_cache',
     use_cache_dir=True,                # Save files in the default user cache dir
-    cache_control=True,                # Use Cache-Control headers for expiration, if available
+    cache_control=True,                # Use Cache-Control response headers for expiration, if available
     expire_after=timedelta(days=1),    # Otherwise expire responses after one day
-    allowable_methods=['GET', 'POST'], # Cache POST requests to avoid sending the same data twice
     allowable_codes=[200, 400],        # Cache 400 responses as a solemn reminder of your failures
-    ignored_parameters=['api_key'],    # Don't match this param or save it in the cache
-    match_headers=True,                # Match all request headers
+    allowable_methods=['GET', 'POST'], # Cache whatever HTTP methods you want
+    ignored_parameters=['api_key'],    # Don't match this request param, and redact if from the cache
+    match_headers=['Accept-Language'], # Cache a different response per language
     stale_if_error=True,               # In case of request errors, use stale cache data if possible
 )
 ```