6 files changed, 62 insertions, 31 deletions
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md
index 1e749f845..cde828c9a 100644
--- a/docs/running/admin_manual.md
+++ b/docs/running/admin_manual.md
@@ -6,14 +6,14 @@ title: Administrator's guide
 # Alaveteli 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" class="glossary">Freedom of Information</a> site, <a href="http://www.whatdotheyknow.com">whatdotheyknow.com</a>.
+  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" class="glossary">Freedom of Information</a> site, <a href="https://www.whatdotheyknow.com">whatdotheyknow.com</a>.
 </p>
 
 ## What's involved?
 
 The overhead in managing a successful FOI website is quite high. Richard, a
 volunteer, wrote a [blog
-post](http://www.mysociety.org/2009/10/13/behind-whatdotheyknow/) about some of
+post](https://www.mysociety.org/2009/10/13/behind-whatdotheyknow/) about some of
 this in 2009.
 
 WhatDoTheyKnow usually has about 3 active volunteers at any one time managing
@@ -141,7 +141,7 @@ user of the site who later develops "Google remorse".
   material down against the public interest in publishing / continuing to
   publish the material.  "Sensitive" personal data will typically require a
   much higher level of public interest.
-* [WhatDoTheyKnow considers](http://www.whatdotheyknow.com/help/privacy#takedown) there to be a
+* [WhatDoTheyKnow considers](https://www.whatdotheyknow.com/help/privacy#takedown) there to be a
   strong public interest in retaining the names of officers or servants of
   public authorities
 * For users who want their name removed entirely from the site, in the first
@@ -213,7 +213,7 @@ Respond to user and point them in the right direction.
 > in public, via our site. To get started click "make a new freedom of
 > information request" at:
 >
-> http://www.whatdotheyknow.com/body/&lt;authority_name&gt;
+> https://www.whatdotheyknow.com/body/&lt;authority_name&gt;
 
 ### Wants advice
 
diff --git a/docs/running/index.md b/docs/running/index.md
index 3db94f713..90461fb3e 100644
--- a/docs/running/index.md
+++ b/docs/running/index.md
@@ -16,13 +16,13 @@ site, you need to make sure day-to-day tasks get done too. Most Alaveteli sites
 are run by a team who allocate some time every day to user support and generally keeping
 the project up to date.
 
-* the [administrator's guide]({{ site.baseurl }}docs/running/admin_manual) describes
+* the [administrator's guide]({{ site.baseurl }}docs/running/admin_manual/) describes
   what you need to do and know to run your site
 
 * we've prepared a checklist of
-  [things to consider]({{ site.baseurl }}docs/running/server)
+  [things to consider]({{ site.baseurl }}docs/running/server/)
   when setting up your production server
 
-* see the [different states a request can be in]({{ site.baseurl }}docs/running/states)
+* see the [different states a request can be in]({{ site.baseurl }}docs/running/states/)
 
 
diff --git a/docs/running/server.md b/docs/running/server.md
index 63ec1800f..1de0ce595 100644
--- a/docs/running/server.md
+++ b/docs/running/server.md
@@ -25,18 +25,14 @@ ask us about hosting.
 ## Cron jobs
 
 Don't forget to set up the cron jobs as outlined in the
-[installation instructions]({{ site.baseurl }}docs/installing/manual_install).
-As of October 2011, they rely on a small program created by mySociety called
-`run-with-lockfile`. A discussion of where the source for this can be found,
-and possible alternatives, lives in
-[Alaveteli issue #112](https://github.com/mysociety/alaveteli/issues/112).
+[installation instructions]({{ site.baseurl }}docs/installing/manual_install/).
 
 ## Webserver configuration
 
 We recommend running your site behind
 [Apache](https://httpd.apache.org) +
 [Passenger](https://www.phusionpassenger.com). Refer to the
-[installation instructions]({{ site.baseurl }}docs/installing/manual_install)
+[installation instructions]({{ site.baseurl }}docs/installing/manual_install/)
 regarding `PassengerMaxPoolSize`, which you should
 experiment with to match your available RAM. It is very unlikely that you'll
 ever need a pool larger than [Passenger's
@@ -49,7 +45,7 @@ Alaveteli ships with a
 
 ## Security
 
-You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config)
+You _must_ change all key-related [config settings]({{ site.baseurl }}docs/customising/config/)
 in `general.yml` from their default values. This includes (but may not be limited to!)
 these settings:
 
@@ -76,11 +72,10 @@ deliverability of your email:
 
 * Set up [SPF records](http://www.openspf.org/) for your domain
 * Set up <a
-  href="http://en.wikipedia.org/wiki/Feedback_loop_(email)#Feedback_loop_links_f
-  or_some_email_providers">feedback loops</a> with the main email providers
+  href="http://wiki.asrg.sp.am/wiki/Feedback_loop_links_for_some_email_providers">feedback loops</a> with the main email providers
   (Hotmail and Yahoo! are recommended)
 * Especially if deploying from Amazon EC2, use an external SMTP relay for
-  sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami)
+  sending outgoing mail. See [Alaveteli EC2 AMI]( {{ site.baseurl }}docs/installing/ami/)
   for more suggestions.
 
 ## Backup
diff --git a/docs/running/states.md b/docs/running/states.md
index 73e49eba7..1c3fb217e 100644
--- a/docs/running/states.md
+++ b/docs/running/states.md
@@ -15,16 +15,16 @@ The request states are defined in the Alaveteli code, and we recommend you use
 them (provided they match the <a href="{{ site.baseurl }}docs/glossary/#foi"
 class="glossary">FOI law</a> in your own jurisdiction). But if you do need to
 customise them, you can &mdash; see
-<a href="{{ site.baseurl }}docs/customising/themes">Customising the request states</a> for details.
+<a href="{{ site.baseurl }}docs/customising/themes/">Customising the request states</a> for details.
 
 ## WhatDoTheyKnow example
 
-Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](http://www.whatdotheyknow.com),
+Requests made on the UK's Alaveteli instance, [WhatDoTheyKnow](https://www.whatdotheyknow.com),
 may be in any of the states described below.
 
 Note that your site doesn't need to use the same states as WhatDoTheyKnow does. For example,
 Kosovo's instance uses slightly different states: see
-[this comparison of their differences]({{ site.baseurl }}docs/running/states_informatazyrtare).
+[this comparison of their differences]({{ site.baseurl }}docs/running/states_informatazyrtare/).
 
 ### States
 
diff --git a/docs/running/states_informatazyrtare.md b/docs/running/states_informatazyrtare.md
index 8097244c5..bd5ff1a1c 100644
--- a/docs/running/states_informatazyrtare.md
+++ b/docs/running/states_informatazyrtare.md
@@ -29,7 +29,7 @@ facilitates this by allowing you to customise the states that are used.
 
 This example is to show clearly that you can use different states depending on
 your local requirements, and how that might look. See [Customising the request
-states]({{ site.baseurl }}docs/customising/themes) for details on how to do this.
+states]({{ site.baseurl }}docs/customising/themes/) for details on how to do this.
 
 ### States used by InformataZyrtare but not WDTK
 
@@ -45,7 +45,7 @@ states]({{ site.baseurl }}docs/customising/themes) for details on how to do this
    * <a href="{{ site.baseurl }}docs/running/states/#user_withdrawn">user_withdrawn</a>
    * <a href="{{ site.baseurl }}docs/running/states/#waiting_response_very_overdue">waiting_response_very_overdue</a>
 
-For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/running/states)) for details.
+For more details, see all the [states used by WhatDoTheyKnow]({{site.baseurl}}docs/running/states/)) for details.
 
 
 ---
diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md
index a3b292cf0..2142bfd47 100644
--- a/docs/running/upgrading.md
+++ b/docs/running/upgrading.md
@@ -5,20 +5,53 @@ title: Upgrading
 Upgrading Alaveteli
 ====================
 
-The developer team policy is that the master branch in git should always
-contain the latest stable release. Therefore, in production, you should usually
-have your software deployed from the master branch, and an upgrade can be
-simply `git pull`.
+<p class="lead">
+  Alaveteli is under active development &mdash; don't let the
+  version you're running get too far behind our latest
+  <a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release</a>.
+  This page describes how to keep your site up-to-date
+</p>
+
+## Master branch contains the latest stable release
+
+The developer team policy is that the `master` branch in git should always
+contain the latest stable release -- so you'll be up to date if you pull from
+the `master` branch. However, on your
+<a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production
+site</a>, you should know precisely what version you're running, and deploy
+Alaveteli from a [*specific* release
+tag](https://github.com/mysociety/alaveteli/releases).
+
+Upgrading may just require pulling in the latest code -- but it may also require
+other changes ("further action"). For this reason, for anything other than a
+*patch* (see below), always read the 
+[`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md)
+document **before** doing an uprade. This way you'll be able to prepare for any
+other changes that might be needed to make the new code work.
+
+## How to upgrade the code
+
+* If you're using Capistrano for deployment,
+  simply [deploy the code]({{site.baseurl}}docs/installing/deploy/#usage):
+  set the repo and branch in `deploy.yml` to be the version you want. 
+  We recommend you set this to the explicit tag name (for example, 
+  `0.18`, and not `master`) so there's no risk of you accidentally deploying
+  a new version before you're aware it's been released.
+* otherwise, you can simply upgrade by running `git pull`
+
+## Patches
 
 Patch version increases (e.g. 1.2.3 &rarr; 1.2.**4**) should not require any further
 action on your part.
 
+## Minor version increases
+
 Minor version increases (e.g. 1.2.4 &rarr; 1.**3**.0) will usually require further
-action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) document to see what's changed since
-your last deployment, paying special attention to anything in the "Upgrade notes"
-sections.
+action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md)
+document to see what's changed since your last deployment, paying special attention
+to anything in the "Upgrade notes" sections.
 
-Any upgrade may include new translations strings, i.e. new or altered messages
+Any upgrade may include new translations strings, that is, new or altered messages
 to the user that need translating to your locale. You should visit Transifex
 and try to get your translation up to 100% on each new release. Failure to do
 so means that any new words added to the Alaveteli source code will appear in
@@ -26,7 +59,10 @@ your website in English by default. If your translations didn't make it to the
 latest release, you will need to download the updated `app.po` for your locale
 from Transifex and save it in the `locale/` folder.
 
-Unless you're using Capistrano for deployment, you should always run the script `scripts/rails-post-deploy` after each
+## Run the post-deploy script
+
+Unless you're [using Capistrano for deployment]({{site.baseurl}}docs/installing/deploy/),
+you should always run the script `scripts/rails-post-deploy` after each
 deployment. This runs any database migrations for you, plus various other
 things that can be automated for deployment.