guides: Modernize guides for environment provisioning

- I don't like individual `brew install` commands littered across a doc.
- Some of the markdown was incorrect.
- These probably need more tweaks, but we can make them once we've done
  the thing for the first time in years.

docs/guides/bootstrap-aws.md

@@ -8,7 +8,7 @@ The new account has a bootstrap role that you should be able to assume to start
 
 There are several ways to do this
 
-###### AWS-CLI
+###### AWS CLI
 
 Make sure your laptop is configured with credentials to access the gds-users account. If you can login in gds-users from the command line, you should be able to get the credentials of an assumed role with the following command:
 
@@ -23,13 +23,13 @@ aws sts assume-role \
 
 ###### AWS-VAULT
 
-Download and install a copy of AWS Vault from the official repo:
-https://github.com/99designs/aws-vault
+`brew cask install aws-vault` on macOS, or `brew install aws-vault` on Linux.
 
 Follow the instructions to set up your initial profile. A good tutorial that explains this step by step can be found here:
 https://medium.com/devopslinks/step-by-step-aws-iam-assumerole-with-aws-vault-configuration-9d5986373c33
 
-After following the tutorial you should have a ``` ~/.aws/config ``` file similar to the example below. You may have more or less profile entries depending on how many environments you have access to:
+After following the tutorial you should have an `~/.aws/config` file similar to the example below.
+
 ```
 [profile readonly]
 region=eu-west-1
@@ -42,14 +42,12 @@ mfa_serial = arn:aws:iam::11111111111:mfa/your.name@email.provider
 ```
 
 After setting up aws-vault you can generate a token by running the following:
+
 ```
 aws-vault exec environmentname -- env
 ```
-For Example:
-```
-aws-vault exec staging -- env
-```  
-Some temporary credentials will be outputted to screen, copy the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and the AWS_SESSION_TOKEN
+
+Some temporary credentials will be shown in the terminal - copy the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and the AWS_SESSION_TOKEN.
 
 Create a new file (e.g. aws_temp_cred) somewhere on your local machine and paste the credentials into it, so it looks similar to the example below
 
@@ -58,9 +56,8 @@ export AWS_ACCESS_KEY_ID=YOURACCESSKEY
 export AWS_SECRET_ACCESS_KEY=YOURSECRETKEY
 export AWS_SESSION_TOKEN=YOURLONGSESSIONTOKEN
 ```
-Now run the source command on the file to make the credentials available for Terraform, for example:
 
-``` source ./aws_temp_cred ```
+Then, `source ./aws_temp_cred`.
 
 ## Setting up Terraform work environment
 

docs/guides/environment-provisioning.md

@@ -3,6 +3,7 @@
 This document discusses how to create a new environment in AWS. Discussion as to the decisions taken can be found in the [architecture/decisions](architecture/decisions) directory, of particular note is [the environment bootstrapping process](architecture/decisions/0009-environment-bootstrapping-process.md).
 
 To clarify terms used here there is a [glossary](#glossary). Throughout this document `<foo>` indicates a value you supply (e.g. a stack name) and:
+
 ```
 bar
 ```
@@ -23,30 +24,21 @@ The general steps for provisioning a new environment are:
 
 ## Requirements
 
-* [Git](https://git-scm.com/) installed via [Xcode cli tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)/[brew](https://brew.sh/)
-* [Terraform = 0.11.14](https://www.terraform.io/downloads.html) installed via that link
-* [ssh-copy-id](https://www.ssh.com/ssh/copy-id) installed via `brew install ssh-copy-id`
-* [aws-cli](https://aws.amazon.com/cli) installed via `brew install awscli` or `pip install awscli`
+* Install [Homebrew](https://brew.sh) on macOS or Linux.
+* Install necessary packages:
 
-If you've not used the aws-cli before run
-```
-aws configure
+```shell
+brew install git tfenv ssh-copy-id awscli
 ```
-to set your access id, secret and the region to use.
-
-## Cloning the repositories
 
-You will need to have cloned the following repositories to your local machine
+* Install the version of Terraform specified in `.terraform-version` with `tfenv install`.
 
-* [govuk-puppet](https://github.com/alphagov/govuk-puppet)
-* [govuk-secrets](https://github.com/alphagov/govuk-secrets)
-* [govuk-aws-data](https://github.com/alphagov/govuk-aws-data)
-* [govuk-aws (this one)](https://github.com/alphagov/govuk-aws)
+* Clone the following repositories to your local machine
 
-e.g.
-```
-git clone git@github.com:alphagov/govuk-secrets.git
-```
+      * [govuk-puppet](https://github.com/alphagov/govuk-puppet)
+      * [govuk-secrets](https://github.com/alphagov/govuk-secrets)
+      * [govuk-aws-data](https://github.com/alphagov/govuk-aws-data)
+      * [govuk-aws (this one)](https://github.com/alphagov/govuk-aws)
 
 > **NOTE: Ensure Puppet has all dependencies installed**
 >
@@ -67,18 +59,22 @@ aws s3 ls $TERRAFORM_BUCKET
 ```
 
 If the bucket is missing you'll see an error:
+
 ```
 An error occurred (NoSuchBucket) when calling the ListObjects operation: The specified bucket does not exist
 ```
+
 otherwise you'll see the bucket's contents, one directory per existing stack:
+
 ```
 PRE blue/
 PRE green/
 PRE govuk/
 ...
 ```
 
-To create an S3 bucket run the following in order to create a bucket and enable versioning on it:
+Create an S3 bucket and enable versioning on it:
+
 ```
 aws s3 mb "s3://${TERRAFORM_BUCKET}"
 aws s3api put-bucket-versioning  \