diff --git a/docs/source/security-basics.rst b/docs/source/security-basics.rst
index ceef9922..5de09278 100644
--- a/docs/source/security-basics.rst
+++ b/docs/source/security-basics.rst
@@ -1,18 +1,19 @@
-Security
-========
+Security basics
+===============
 
 .. important::
 
-   You should not run JupyterHub without SSL encryption on a public network
+   You should not run JupyterHub without SSL encryption on a public network.
 
-Security is the most important aspect of configuring Jupyter. There are four
-main aspects of the security configuration:
+Security is the most important aspect of configuring Jupyter. Three
+configuration settings and one best practice are the main aspects of security
+configuration:
 
-1. `SSL encryption <ssl-encryption>`_ (to enable HTTPS)
-2. `Cookie secret <cookie-secret>`_ (a key for encrypting browser cookies)
-3. Proxy `authentication token <authentication-token>`_ (used for the Hub and
+1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
+2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
+3. Proxy :ref:`authentication token <authentication-token>` (used for the Hub and
    other services to authenticate to the Proxy)
-4. Periodic `security audits <security-audits>`_
+4. Periodic :ref:`security audits <security-audits>`
 
 The Hub hashes all secrets (e.g., auth tokens) before storing them in its
 database. A loss of control over read-access to the database should have no
@@ -100,11 +101,10 @@ An example would be to generate this file with:
 
     openssl rand -hex 32 > /srv/jupyterhub/cookie_secret
 
-
 In most deployments of JupyterHub, you should point this to a secure location on
 the file system, such as ``/srv/jupyterhub/cookie_secret``. If the cookie secret
 file doesn't exist when the Hub starts, a new cookie secret is generated and
-stored in the file. The file must not be readable by group or other or the
+stored in the file. The file must not be readable by ``group`` or ``other`` or the
 server won't start. The recommended permissions for the cookie secret file are
 ``600`` (owner-only rw).
 
@@ -123,7 +123,7 @@ Hub. If you set it dynamically as above, all users will be logged out each time
 the Hub starts.
 
 You can also set the cookie secret in the configuration file
-itself,``jupyterhub_config.py``, as a binary string:
+itself, ``jupyterhub_config.py``, as a binary string:
 
 .. code-block:: python
 
@@ -173,4 +173,4 @@ good practice to keep JupyterHub, configurable-http-proxy, and nodejs
 versions up to date.
 
 A handy website for testing your deployment is
-[Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html).
+`Qualsys' SSL analyzer tool <https://www.ssllabs.com/ssltest/analyze.html>`_.
diff --git a/docs/source/websecurity.md b/docs/source/websecurity.md
index e9484a1c..3ead7782 100644
--- a/docs/source/websecurity.md
+++ b/docs/source/websecurity.md
@@ -1,6 +1,11 @@
-# Web Security and JupyterHub's design
+# Security Overview
 
-## JupyterHub's design approach
+The **Security Overview** section helps you learn about the design of JupyterHub
+with respect to web security, the semi-trusted user, and the available
+mitigations to protect untrusted users from each other. It also helps you
+obtain a deeper understanding of how JupyterHub works.
+
+## Semi-trusted and untrusted users
 
 JupyterHub is designed to be a *simple multi-user server for modestly sized
 groups* of **semi-trusted** users. While the design reflects serving semi-trusted
@@ -18,7 +23,7 @@ single-user servers and the Hub, or between single-user servers and each
 other, since browsers see the whole thing (proxy, Hub, and single user
 servers) as a single website (i.e. single domain).
 
-## How to protect users from each other
+## Protect users from each other
 
 To protect users from each other, a user must **never** be able to write arbitrary
 HTML and serve it to another user on the Hub's domain. JupyterHub's
@@ -46,10 +51,10 @@ If any additional services are run on the same domain as the Hub, the services
 **must never** display user-authored HTML that is neither *sanitized* nor *sandboxed*
 (e.g. IFramed) to any user that lacks authentication as the author of a file.
 
-## Mitigate security issues through configuration options
+## Mitigate security issues
 
 There are two main approaches to mitigating these issues with configuration
-options provided by JupyterHub:
+options provided by JupyterHub.
 
 ### Enable subdomains
 
@@ -64,7 +69,10 @@ institutional domains, wildcard DNS and SSL are not available. **If you do plan
 to serve untrusted users, enabling subdomains is highly encouraged**, as it
 resolves the cross-site issues.
 
-### Steps to take when subdomains can not be used
+### Unavailable subdomains
+
+When subdomains are not available or not desirable, three steps can be taken
+to secure JupyterHub from untrusted users.
 
 #### Disable user config