new entries and small tidies in glossary around admin/superuser

4 files changed, 103 insertions, 16 deletions

diff --git a/docs/glossary.md b/docs/glossary.md
index b5239a32a..3ae5e6a3c 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -16,6 +16,7 @@ Definitions
 
 <ul class="definitions">
   <li><a href="#alaveteli">Alaveteli</a></li>
+  <li><a href="#admin">admin interface</a></li>
   <li><a href="#agnostic">asker agnostic</a></li>
   <li><a href="#authority">authority</a></li>
   <li><a href="#blackhole">black hole</a></li>
@@ -42,6 +43,7 @@ Definitions
   <li><a href="#sass">Sass</a></li>
   <li><a href="#staging">staging site</a></li>
   <li><a href="#state">state</a></li>
+  <li><a href="#super">superuser</a></li>
   <li><a href="#theme">theme</a></li>
 </ul>
 
@@ -79,6 +81,40 @@ Definitions
   </dd>
 
   <dt>
+    <a name="admin">admin interface</a> (also: admin)
+  </dt>
+  <dd>
+    The <strong>admin interface</strong> allows users who have
+    <a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a>
+    administrator privilege to manage some aspects of how your
+    Alaveteli site runs.
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          You can access your installation's <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>
+          at <code>/admin</code>.
+        </li>
+        <li>
+          To grant a user admin privilege, log into the admin and change
+          their <em>Admin level</em> to "super" (or revoke the privilege
+          by changing it to "none").
+        </li>
+        <li>
+          On a newly-installed Alaveteli system, you can grant yourself
+          admin privilege by using the 
+          <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency
+          user</a>.
+        </li>
+        <li>
+          For lots more about running an Alaveteli site, see the
+          <a href="{{ site.baseurl }}running/admin_manual">adminstrator's guide</a>.
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
     <a name="agnostic">asker agnostic</a>
   </dt>
   <dd>
@@ -266,7 +302,7 @@ Definitions
   </dd>
 
   <dt>
-    <a name="foi">Freedom of Information</a> (also FOI)
+    <a name="foi">Freedom of Information</a> (also: FOI)
   </dt>
   <dd>
     <strong>Freedom of information</strong> laws allow access by the general public
@@ -287,7 +323,7 @@ Definitions
   </dd>
 
   <dt>
-    <a name="git">git</a> (also github,  git repository, and git repo)
+    <a name="git">git</a> (also: github,  git repository, and git repo)
   </dt>
   <dd>
     We use a popular source code control system called <strong>git</strong>. This
@@ -617,7 +653,7 @@ Definitions
   </dd>
 
   <dt>
-    <a name="rails">Ruby on Rails</a> (also Rails)
+    <a name="rails">Ruby on Rails</a> (also: Rails)
   </dt>
   <dd>
     Alaveteli is written in the Ruby programming language, using
@@ -721,6 +757,31 @@ Definitions
   </dd>
 
   <dt>
+    <a name="super">superuser</a> (also: super privilege)
+  </dt>
+  <dd>
+    A <strong>superuser</strong> is an Alaveteli user who has been granted
+    the privilege to use all features of the
+    <a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>.
+    <div class="more-info">
+      <p>More information:</p>
+      <ul>
+        <li>
+          To grant a user admin privilege, log into the admin and change
+          their <em>Admin level</em> to "super" (or revoke the privilege
+          by changing it to "none").
+        </li>
+        <li>
+          On a newly-installed Alaveteli system, you can grant yourself
+          admin privilege by using the 
+          <a href="{{ site.baseurl }}docs/glossary/#emergency" class="glossary__link">emergency
+          user</a>.
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
     <a name="theme">theme</a>
   </dt>
   <dd>
diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md
index 8c9e2a8d6..9cad6b5b9 100644
--- a/docs/installing/manual_install.md
+++ b/docs/installing/manual_install.md
@@ -351,7 +351,12 @@ Example `development` section of `config/database.yml`:
 Make sure that the user specified in `database.yml` exists, and has full
 permissions on these databases.
 
-As the user needs the ability to turn off constraints whilst running the tests they also need to be a superuser. If you don't want your database user to be a superuser, you can add this line to the `test` section in `database.yml` (as seen in `config/database.yml-example`):
+As the user needs the ability to turn off constraints whilst running the tests
+they also need to be a superuser (clarification: a <em>Postgres</em> superuser,
+not an Alaveteli
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">superuser</a>).
+If you don't want your database user to be a superuser, you can add this line
+to the `test` section in `database.yml` (as seen in `config/database.yml-example`):
 
     constraint_disabling: false
 
diff --git a/docs/installing/next_steps.md b/docs/installing/next_steps.md
index 4199daabf..20c69a504 100644
--- a/docs/installing/next_steps.md
+++ b/docs/installing/next_steps.md
@@ -14,7 +14,9 @@ Alaveteli ships with an
 <a href="{{site.baseurl}}docs/glossary/#emergency" class="glossary__link">emergency user</a>
 that has access to the admin. So when you've just created a new site, you
 should sign up to create your own account, then log into admin as the emergency
-user to promote your new account to be an administrator with *super* privileges.
+user to promote your new account to be an administrator with
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a>
+privilege.
 
 As soon as that's done, disable the emergency user, because you don't need to
 use it any more: you've superseded it with your new admin account.
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index d166cb859..a846732f3 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -7,12 +7,23 @@ title: Administrator's guide
 
 <p class="lead">
   What is it like running an Alaveteli site? This guide explains what you can
-  expect, and the types of problem that you might encounter. It includes
-  examples of how mySociety manages their own <a href="/docs/glossary/#foi"
+  expect, and the types of problem that you might encounter. At mySociety,
+  we've been running our own <a href="/docs/glossary/#foi"
   class="glossary__link">Freedom of Information</a> site, <a
-  href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>.
+  href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>, since 2008,
+  so we've included lots of examples from our own experience.
+  
 </p>
 
+<div class="attention-box helpful-hint">
+  <p>
+    <b>Before you start...</b>
+    This admin guide assumes your Alaveteli site is already up and running.
+    If it's not, you need to follow the steps for
+    <a href="{{ site.baseurl }}docs/getting_started/">getting started with Alaveteli</a>.
+  </p>
+</div>
+
 In this guide:
 
 <ul class="toc">
@@ -55,7 +66,8 @@ times.
 
 Administration tasks can be split into [**maintenance**]({{ site.baseurl }}docs/running/admin_manual/#maintenance) and [**user support**]({{ site.baseurl }}docs/running/admin_manual/#user-support).
 The boundaries of these tasks is in fact quite blurred; the main distinction is
-that the former happen exclusively through the web admin interface, whereas the
+that the former happen exclusively through the web 
+<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">admin interface</a>, whereas the
 latter are mediated by email directly with end users (but often result in
 actions through the web admin interface).
 
@@ -308,17 +320,24 @@ line, and piping the contents of that file into the mail handling script. e.g.
 
 ### Administrator privileges and accessing the admin interface
 
-The administrative interface is at the URL `/admin`.
+The 
+<a href="{{ site.baseurl }}docs/glossary/#admin" class="glossary__link">administrative interface</a>
+is at the URL `/admin`.
 
-Only users with the `super` admin level can access the admin interface. Users
-create their own accounts in the usual way, and then administrators can give
-them `super` privileges.
+Only users with the
+<a href="{{ site.baseurl }}docs/glossary/#super" class="glossary__link">super</a>
+admin level can access the admin interface. To make a new administrator,
+create a user account in the usual way (signing in using the web front-end),
+and then have an existing administrator to grant them *super* privileges.
 
-There is an emergency user account which can be accessed via
-`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and
+Obviously, you can't do this for the very first administrator on a brand
+new Alavetlei installation. So there is an emergency user account which can be
+accessed via `/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and
 `ADMIN_PASSWORD`, which are set in `general.yml`.  To bootstrap the
 first `super` level accounts, you will need to log in as the emergency
-user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`.
+user. When you have granted *super* privileges to at least one existing user,
+you can disable the emergency user account by setting `DISABLE_EMERGENCY_USER`
+to `true` in `general.yml`.
 
 Users with the superuser role also have extra privileges in the website
 front end, such as being able to categorise any request, being able to view