Edit auth docs

docs/source/authenticators-users-basics.md

@@ -1,28 +1,27 @@
 # Authentication and Users
 
 The default Authenticator uses [PAM][] to authenticate system users with
-their username and password. The default behavior of this Authenticator
-is to allow any user with an account and password on the system to login.
+their username and password. With the default Authenticator, any user
+with an account and password on the system will be allowed to login.
 
-## Creating a whitelist of users
+## Create a whitelist of users
 
-You can restrict which users are allowed to login with `Authenticator.whitelist`:
+You can restrict which users are allowed to login with a whitelist,
+`Authenticator.whitelist`:
 
 
 ```python
 c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}
 ```
 
-Users listed in the whitelist are added to the Hub database when the Hub is
+Users in the whitelist are added to the Hub database when the Hub is
 started.
 
-## Managing Hub administrators
+## Configure admins (`admin_users`)
 
-### Configuring admins (`admin_users`)
-
-Admin users of JupyterHub, `admin_users`, have the ability to add and remove
-users from the user `whitelist` or to take actions on the users' behalf,
-such as stopping and restarting their servers.
+Admin users of JupyterHub, `admin_users`, can add and remove users from
+the user `whitelist`. `admin_users` can take actions on other users'
+behalf, such as stopping and restarting their servers.
 
 A set of initial admin users, `admin_users` can configured be as follows:
 
@@ -32,44 +31,49 @@ c.Authenticator.admin_users = {'mal', 'zoe'}
 Users in the admin list are automatically added to the user `whitelist`,
 if they are not already present.
 
-### Admin access to other users' notebook servers (`admin_access`)
+## Give admin access to other users' notebook servers (`admin_access`)
 
-By default the admin users do not have permission to log in *as other users*
-since the default `JupyterHub.admin_access` setting is False.
-If `JupyterHub.admin_access` is set to True, then admin users have permission
-to log in *as other users* on their respective machines, for debugging.
-**You should make sure your users know if admin_access is enabled.**
+Since the default `JupyterHub.admin_access` setting is False, the admins
+do not have permission to log in to the single user notebook servers
+owned by *other users*. If `JupyterHub.admin_access` is set to True,
+then admins have permission to log in *as other users* on their
+respective machines, for debugging. **As a courtesy, you should make
+sure your users know if admin_access is enabled.**
 
-Note: additional configuration examples are provided in this guide's
-[Configuration Examples section](./config-examples.html).
+## Add or remove users from the Hub
 
-### Add or remove users from the Hub
+Users can be added to and removed from the Hub via either the admin
+panel or the REST API. When a user is **added**, the user will be
+automatically added to the whitelist and database. Restarting the Hub
+will not require manually updating the whitelist in your config file,
+as the users will be loaded from the database.
 
-Users can be added to and removed from the Hub via either the admin panel or
-REST API.
+After starting the Hub once, it is not sufficient to **remove** a user
+from the whitelist in your config file. You must also remove the user
+from the Hub's database, either by deleting the user from JupyterHub's
+admin page, or you can clear the `jupyterhub.sqlite` database and start
+fresh.
 
-If a user is **added**, the user will be automatically added to the whitelist
-and database. Restarting the Hub will not require manually updating the
-whitelist in your config file, as the users will be loaded from the database.
+## Use LocalAuthenticator to create systems users
 
-After starting the Hub once, it is not sufficient to **remove** a user from
-the whitelist in your config file. You must also remove the user from the Hub's
-database, either by deleting the user from the admin page, or you can clear
-the `jupyterhub.sqlite` database and start fresh.
-
-The default `PAMAuthenticator` is one case of a special kind of authenticator, called a
-`LocalAuthenticator`, indicating that it manages users on the local system. When you add a user to
-the Hub, a `LocalAuthenticator` checks if that user already exists. Normally, there will be an
-error telling you that the user doesn't exist. If you set the configuration value
+The `LocalAuthenticator` is a special kind of authenticator that has
+the ability to manage users on the local system. When you try to add a
+new user to the Hub, a `LocalAuthenticator` will check if the user
+already exists. If you set the configuration value, `create_system_users`,
+to `True` in the configuration file, the `LocalAuthenticator` has
+the privileges to add users to the system. The setting in the config
+file is:
 
 ```python
 c.LocalAuthenticator.create_system_users = True
 ```
 
-however, adding a user to the Hub that doesn't already exist on the system will result in the Hub
-creating that user via the system `adduser` command line tool. This option is typically used on
-hosted deployments of JupyterHub, to avoid the need to manually create all your users before
-launching the service. It is not recommended when running JupyterHub in situations where
-JupyterHub users maps directly onto UNIX users.
+Adding a user to the Hub that doesn't already exist on the system will
+result in the Hub creating that user via the system `adduser` command
+line tool. This option is typically used on hosted deployments of
+JupyterHub, to avoid the need to manually create all your users before
+launching the service. This approach is not recommended when running
+JupyterHub in situations where JupyterHub users map directly onto the
+system's UNIX users.
 
 [PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module