Re-organize documentation to match new structure

- Added docs on authentication methods we support
- Split up 'users' docs into 3 separate page, to match
  different kinds of content
- Make docs slightly more verbose in the service of
  completeness

admin/configuration/culling.md

@@ -0,0 +1,11 @@
+# User server culling
+
+To ensure efficient resource usage, user servers without interactive usage for a
+period of time (default 1h) are automatically stopped (via
+[jupyterhub-idle-culler](https://github.com/jupyterhub/jupyterhub-idle-culler)).
+This means your notebook server might be stopped for inactivity even if you have
+a long running process in the notebook. This timeout can be configured.
+
+This has the same effect as a user stopping their own server. User servers stopping doesn't lose any data in your home directories. However, any packages temporarily installed via `!pip` or `!conda` are cleared, to make sure that everyone in the hub is operating from the same clean environment as much as possible. Active notebooks have their kernel killed as well.
+
+There is currently no maximum time limit for a user's notebook.

admin/configuration/login.md

@@ -0,0 +1,25 @@
+# User authentication & authorization
+
+(admin/configuration/authentication)=
+## Authentication
+
+Users can prove who they are by logging in via an *authentication provider*. Currently, the following providers are supported:
+
+1. *Google*. This includes public `@gmail.com` accounts, as well as [Google Workspace](https://workspace.google.com/) accounts set up for your workspace or university. If you use the GMail interface to access your work / university email, it can be used here.
+
+2. [*GitHub*](https://github.com/). Extremely popular community of people creating, publishing and collaborating on code. Accounts are free, and many people already have them especially since the target community for most hubs are people who also write some kind of code.
+
+3. [*ORCID*](https://orcid.org/). Everyone who has published a paper has one of these, and anyone else can easily sign up. Almost exclusively used by researchers.
+
+4. ???. We could probably support other authentication providers, depending on your specific needs and the provider's complexity. Please reach out to us if none of these 3 work.
+
+## Authorization
+
+Not everyone who can authenticate is granted access to the hub - that
+would mean everyone with a `@gmail.com` account can log in if you use Google as your authentication provider! Instead, we support multiple ways for hub admins to specify which users are *authorized* to be on the hub.
+
+Currently, there are only two supported methods:
+
+1. Manually add users via the admin panel in JupyterHub
+2. (Google only) Allow all users who are logged in via aparticular domain - so you can allow access to anyone who is part of your organization or educational institution.
+

admin/howto/access-server.md

@@ -0,0 +1,30 @@
+# Access a user's server
+
+Accessing a user's server is very useful when trying to debug or reproduce an issue they might have. This facility is available to admins via the admin panel. 
+
+1. You can access the admin panel by clicking the 'Admin' button in the top bar
+   in your hub control panel.  Alternatively, you can go to this URL in our
+   browser: `https://<your-hub-url>/hub/admin`.
+
+2. You can click `access server` to gain control of a user's currently running server. If it isn't running, you can click `start server` first and wait for it to start.
+
+   ```{figure} ../../images/access-server.png
+   Clicking "access server" will allow you to control the user's session.
+   ```
+
+3. This will bring you to the default interface that the user would have seen if they had just logged into the hub. From here, you can navigate to the notebook the user has reported issues with, and help them debug.
+
+   ```{warning}
+   If you both work on the same notebook at the same time, you will just
+   overwrite each other's code! The state of the notebook will be that of
+   whoever saved the notebook last. There is no Google Docs' style
+   real-time collaboration yet, although [it is coming](https://github.com/jupyterlab/rtc)
+   ```
+
+   ```{warning}
+   When you control a user's server, all of your actions will be run *as
+   if the user ran it themselves*. This can be confusing for some users
+   and is generally not best-practice. We recommend telling users when
+   you are taking over their session, and using this feature mostly to understand what the user was trying to do, rather than to make major
+   changes to their code or notebook outputs.
+    ```

admin/howto/manage-users.md

@@ -0,0 +1,45 @@
+# Manage access to the hub
+
+The **Administrator Panel** can be used to maintain the list of users
+who are authorized to use your hub. You can access this panel by clicking
+the 'Admin' button in the top bar in your hub control panel.
+Alternatively, you can go to this URL in your browser:
+`https://<your-hub-url>/hub/admin`
+
+## To add users
+
+1. Click the `Add Users` button. The `Add Users` dialog box will pop up.
+2. Add one or more users, and hit the `Add Users` button to authorize all the users you just added.
+
+
+````{panels}
+:container: full-width
+:card: border-1
+```{figure} ../../images/add-users-button.png
+The add users button in the Administrator Panel.
+```
+---
+```{figure} ../../images/add-users-form.png
+Fill in usernames and optionally make them administrators. You can add multiple users at once by putting a username on each line.
+```
+````
+
+## Finding usernames
+
+Access is granted or revoked based on `usernames`, and these depend on the kind
+of (authentication provider)[admin/configuration/authentication] your hub is
+using. In general, it matches whatever the visible 'username' in your
+authentication provider is. The table below lists the available providers, and
+how to determine their username.
+
+
+| Provider | Username |
+|-|-|
+| Google | Email address |
+| GitHub | GitHub user name |
+| ORCID | ORCID id |
+
+
+## To remove users
+
+????

index.md

@@ -25,11 +25,24 @@ admin/support
 admin/environment
 admin/interfaces
 admin/data
-admin/users
 admin/migrate
 admin/content
 ```
 
+```{toctree}
+:caption: Administrator configuration guides
+:maxdepth: 1
+admin/configuration/login
+admin/configuration/culling
+```
+
+```{toctree}
+:caption: Administrator how-to guides
+:maxdepth: 1
+admin/howto/manage-users
+admin/howto/access-server
+```
+
 ```{toctree}
 :maxdepth: 1
 :caption: User's Guide