diff --git a/docs/examples/gitlab.md b/docs/examples/gitlab.md
index 10e6453da7a41b52555b1bfc59c6799fb1110521..95ee0f9b149bef11ac53daad4c275fabc40b6221 100644
--- a/docs/examples/gitlab.md
+++ b/docs/examples/gitlab.md
@@ -1,6 +1,6 @@
-## How to configure runner for GitLab CE integration tests (uses confined Docker executor)
+# How to configure GitLab Runner for GitLab CE integration tests
 
-### 1. Register the runner
+We will register the Runner using a confined Docker executor.
 
 The registration token can be found at `https://gitlab.com/project_namespace/project_name/runners`.
 You can export it as a variable and run the command below as is:
@@ -16,8 +16,6 @@ gitlab-ci-multi-runner register \
 --docker-postgres latest --docker-redis latest
 ```
 
-----
-
 You now have a GitLab CE integration testing instance with bundle caching.
 Push some commits to test it.
 
diff --git a/docs/executors/kubernetes.md b/docs/executors/kubernetes.md
index b2bf65ace7e1f78ad7b21896d5ac487f2e57ccd3..f0c8b6ca46b79adf3b47b2fc0a2578c810934388 100644
--- a/docs/executors/kubernetes.md
+++ b/docs/executors/kubernetes.md
@@ -1,4 +1,7 @@
-# The Kubernetes executor (**EXPERIMENTAL**)
+# The Kubernetes executor
+
+>**Note:**
+This executor is **EXPERIMENTAL**.
 
 GitLab Runner can use Kubernetes to run builds on a kubernetes cluster. This is
 possible with the use of the **Kubernetes** executor.
@@ -12,13 +15,6 @@ yaml. The names for these containers are as follows:
 - The build container is `build`
 - The services containers are `svc-X` where `X` is `[0-9]+`
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Workflow
 
 The Kubernetes executor divides the build into multiple steps:
diff --git a/docs/executors/shell.md b/docs/executors/shell.md
index b0daca861440d9078723d633bc04da293b01e297..cbff42b4ef9ad20dc73ba3f38b3985ad72a48878 100644
--- a/docs/executors/shell.md
+++ b/docs/executors/shell.md
@@ -5,18 +5,6 @@ locally to the machine that the Runner is installed. It supports all systems on
 which the Runner can be installed. That means that it's possible to use scripts
 generated for Bash, Windows PowerShell and Windows Batch.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Running as unprivileged user](#running-as-unprivileged-user)
-- [Security](#security)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 The scripts can be run as unprivileged user if the `--user` is added to the
diff --git a/docs/executors/ssh.md b/docs/executors/ssh.md
index 391c32b00107d271a0c5098eea50a0f74ad445ac..e1f012a179575899347fdaf5a706c67c1628a1b0 100644
--- a/docs/executors/ssh.md
+++ b/docs/executors/ssh.md
@@ -7,17 +7,6 @@ is currently not supported.
 This is a simple executor that allows you to execute builds on a remote machine
 by executing commands over SSH.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Security](#security)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 To use the SSH executor you need to specify `executor = "ssh"` under the
diff --git a/docs/executors/virtualbox.md b/docs/executors/virtualbox.md
index 698db019762a05f529cfcfc138f7a4fd1cb1ecf8..adbe5fcbb05ad10990f3973b6cf9dbe78eab1070 100644
--- a/docs/executors/virtualbox.md
+++ b/docs/executors/virtualbox.md
@@ -1,6 +1,7 @@
 # VirtualBox
 
-> Note: The Parallels executor works the same as the VirtualBox executor. The
+>**Note:**
+The Parallels executor works the same as the VirtualBox executor. The
 caching feature is currently not supported.
 
 VirtualBox allows you to use VirtualBox's virtualization to provide a clean
@@ -8,19 +9,6 @@ build environment for every build. This executor supports all systems that can
 be run on VirtualBox. The only requirement is that the virtual machine exposes
 its SSH server and provide a bash-compatible shell.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Create a new base virtual machine](#create-a-new-base-virtual-machine)
-- [Create a new Runner](#create-a-new-runner)
-- [How it works](#how-it-works)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 The project's source code is checked out to: `~/builds/<namespace>/<project-name>`.
diff --git a/docs/faq/README.md b/docs/faq/README.md
index de7454765cfbf147b452dfeca9db81c8fd9611c7..012c6b3674da13ed700d350c2e7f52bee0db27c0 100644
--- a/docs/faq/README.md
+++ b/docs/faq/README.md
@@ -1,23 +1,6 @@
 # FAQ
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
-- [1. Where are logs stored when run as a service?](#1-where-are-logs-stored-when-run-as-a-service)
-- [2. Run in `--debug` mode](#2-run-in---debug-mode)
-- [3. I get a PathTooLongException during my builds on Windows](#3-i-get-a-pathtoolongexception-during-my-builds-on-windows)
-- [4. I'm seeing `x509: certificate signed by unknown authority`](#4-im-seeing-x509-certificate-signed-by-unknown-authority)
-- [5. I get `Permission Denied` when accessing the `/var/run/docker.sock`](#5-i-get-permission-denied-when-accessing-the-varrundockersock)
-- [6. The Docker executor gets timeout when building Java project.](#6-the-docker-executor-gets-timeout-when-building-java-project)
-- [7. I get 411 when uploading artifacts.](#7-i-get-411-when-uploading-artifacts)
-- [8. I can't run Windows BASH scripts; I'm getting `The system cannot find the batch label specified - buildscript`.](#8-i-cant-run-windows-bash-scripts-im-getting-the-system-cannot-find-the-batch-label-specified---buildscript)
-- [9. My gitlab runner is on Windows. How can I get colored output on the web terminal?](#9-my-gitlab-runner-is-on-windows-how-can-i-get-colored-output-on-the-web-terminal)
-- [10. "warning: You appear to have cloned an empty repository."](#10-warning-you-appear-to-have-cloned-an-empty-repository)
-- [11. `"launchctl" failed: exit status 112, Could not find domain for`](#11-launchctl-failed-exit-status-112-could-not-find-domain-for)
-- [12. `Failed to authorize rights (0x1) with status: -60007.`](#12-failed-to-authorize-rights-0x1-with-status--60007)
-- [13. `The service did not start due to a logon failure` error when starting service on Windows](#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+Some Frequently Asked Questions about GitLab Runner.
 
 ## 1. Where are logs stored when run as a service?
 
@@ -241,4 +224,4 @@ and the service should be started properly.
 
 [microsoft-manually-set-seservicelogonright]: https://technet.microsoft.com/en-us/library/dn221981
 [microsoft-ntrights-download]: https://www.microsoft.com/en-us/download/details.aspx?id=17657
-[microsoft-ntrights-usage-on-win7]: https://technet.microsoft.com/en-us/library/dd548356(WS.10).aspx
\ No newline at end of file
+[microsoft-ntrights-usage-on-win7]: https://technet.microsoft.com/en-us/library/dd548356(WS.10).aspx
diff --git a/docs/install/autoscaling.md b/docs/install/autoscaling.md
index affc69c56db1a46591e8678bfabf3a5aef88c450..6a3bb94e1547c13b0caa2f4b0ba018c47fff7b8d 100644
--- a/docs/install/autoscaling.md
+++ b/docs/install/autoscaling.md
@@ -5,22 +5,6 @@
 For an overview of the auto-scale architecture, take a look at the
 [comprehensive documentation on auto-scaling](../configuration/autoscale.md).
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Prepare the environment](#prepare-the-environment)
-- [Prepare the Docker Registry and Cache Server](#prepare-the-docker-registry-and-cache-server)
-    - [Install Docker Registry](#install-docker-registry)
-    - [Install the cache server](#install-the-cache-server)
-- [Configure GitLab Runner](#configure-gitlab-runner)
-- [Upgrading the Runner](#upgrading-the-runner)
-- [Manage the Docker Machines](#manage-the-docker-machines)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Prepare the environment
 
 In order to use the auto-scale feature, Docker and GitLab Runner must be
diff --git a/docs/install/bleeding-edge.md b/docs/install/bleeding-edge.md
index 71da697d4901aa5c29b8dbdfb7a656393ac75c00..51c94ebfead5fbfad345f1dcc99ba6c7a43c940b 100644
--- a/docs/install/bleeding-edge.md
+++ b/docs/install/bleeding-edge.md
@@ -1,6 +1,10 @@
-## Bleeding edge releases (development)
+# Bleeding edge releases
 
-### Download the standalone binaries
+>**Note:**
+These are the latest, probably untested releases of GitLab Runner built straight
+from `master` branch. Use at your own risk.
+
+## Download the standalone binaries
 
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-linux-386
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-linux-amd64
@@ -13,13 +17,13 @@
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-freebsd-amd64
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-freebsd-arm
 
-You can then run the runner with:
+You can then run the Runner with:
 ```bash
 chmod +x gitlab-ci-multi-runner-linux-amd64
 ./gitlab-ci-multi-runner-linux-amd64 run
 ```
 
-### Download one of the packages for Debian or Ubuntu
+## Download one of the packages for Debian or Ubuntu
 
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/deb/gitlab-ci-multi-runner_i386.deb
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/deb/gitlab-ci-multi-runner_amd64.deb
@@ -31,7 +35,7 @@ You can then install it with:
 dpkg -i gitlab-ci-multi-runner_386.deb
 ```
 
-### Download one of the packages for RedHat or CentOS
+## Download one of the packages for RedHat or CentOS
 
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/rpm/gitlab-ci-multi-runner_i686.rpm
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/rpm/gitlab-ci-multi-runner_amd64.rpm
@@ -43,7 +47,7 @@ You can then install it with:
 rpm -i gitlab-ci-multi-runner_386.rpm
 ```
 
-### Download any other tagged release
+## Download any other tagged release
 
 Simply replace `master` with either `tag` (v0.2.0 or 0.4.2) or `latest` (the latest
 stable). For a list of tags see <https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tags>.
diff --git a/docs/install/docker.md b/docs/install/docker.md
index 0fe021e03cdcb9f66f96070c16374914a8e637d0..83cdfa6f58ce7a25b88bc77787afffbae37cde4a 100644
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@@ -1,6 +1,8 @@
-## Run gitlab-runner in a container
+# Run GitLab Runner in a container
 
-### Docker image installation and configuration
+This is how you can run GitLab Runner inside a Docker container.
+
+## Docker image installation and configuration
 
 Install Docker first:
 
@@ -8,7 +10,7 @@ Install Docker first:
 curl -sSL https://get.docker.com/ | sh
 ```
 
-We need to mount a config volume into our gitlab-runner container to
+We need to mount a config volume into our `gitlab-runner` container to
 be used for configs and other resources:
 
 ```bash
@@ -18,7 +20,7 @@ docker run -d --name gitlab-runner --restart always \
   gitlab/gitlab-runner:latest
 ```
 
-OR you can use a config container to mount your custom data volume:
+Or, you can use a config container to mount your custom data volume:
 
 ```bash
 docker run -d --name gitlab-runner-config \
@@ -31,7 +33,7 @@ docker run -d --name gitlab-runner --restart always \
     gitlab/gitlab-runner:latest
 ```
 
-If you plan on using Docker as the method of spawning runners, you will need to
+If you plan on using Docker as the method of spawning Runners, you will need to
 mount your docker socket like this:
 
 ```bash
@@ -66,7 +68,7 @@ The runner should is started already and you are ready to build your projects!
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
-### Update
+## Update
 
 Pull the latest version:
 
@@ -92,7 +94,7 @@ docker run -d --name gitlab-runner --restart always \
 **Note**: you need to use the same method for mounting you data volume as you
     did originally (`-v /srv/gitlab-runner/config:/etc/gitlab-runner` or `--volumes-from gitlab-runner`)
 
-### Installing Trusted SSL Server Certificates
+## Installing trusted SSL server certificates
 
 If your GitLab CI server is using self-signed SSL certificates then you should
 make sure the GitLab CI server certificate is trusted by the gitlab-ci-multi-runner
@@ -108,7 +110,7 @@ want gitlab-ci-multi-runner to trust. The gitlab-ci-multi-runner container will
 import the `ca.crt` file on startup so if your container is already running you
 may need to restart it for the changes to take effect.
 
-### Alpine Linux
+## Alpine Linux
 
 You can also use alternative [Alpine Linux](https://www.alpinelinux.org/) based image with much smaller footprint:
 ```
@@ -120,7 +122,7 @@ gitlab/gitlab-runner    alpine              7c431ac8f30f        13 hours ago
 
 The original `gitlab/gitlab-runner:latest` is based on Ubuntu 14.04 LTS.
 
-### SELinux
+## SELinux
 
 Some distributions (CentOS, RedHat, Fedora) use SELinux by default to enhance the security of the underlying system.
 
@@ -135,10 +137,10 @@ Install the `selinux-dockersock` and to resolve the issue: https://github.com/dp
 1. Run docker with `:Z` on volumes:
 
 ```bash
-    docker run -d --name gitlab-runner --restart always \
-      -v /var/run/docker.sock:/var/run/docker.sock \
-      -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
-      gitlab/gitlab-runner:latest
+docker run -d --name gitlab-runner --restart always \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
+  gitlab/gitlab-runner:latest
 ```
 
 More information about the cause and resolution can be found here:
diff --git a/docs/install/freebsd.md b/docs/install/freebsd.md
index e8208171f37af1e9beb6cb68457c1fa4d0a4b247..ba07ee954b04efaf3598dc1e586d26febbd41b6e 100644
--- a/docs/install/freebsd.md
+++ b/docs/install/freebsd.md
@@ -1,135 +1,137 @@
 # Install on FreeBSD
 
-Create gitlab-runner user and group:
-
-```bash
-sudo pw group add -n gitlab-runner
-sudo pw user add -n gitlab-runner -g gitlab-runner -s /usr/local/bin/bash
-sudo mkdir /home/gitlab-runner
-sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner
-```
-
-Download the binary for your system:
-
-```bash
- sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-amd64
- sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-386
-```
-
-Give it permissions to execute:
-
-```bash
-sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
-```
-
-Create empty log file with correct permissions:
-
-```bash
-sudo touch /var/log/gitlab_runner.log && sudo chown gitlab-runner:gitlab-runner /var/log/gitlab_runner.log
-```
-
-Create rc.d directory in case it does not exist:
-
-```bash
-mkdir -p /usr/local/etc/rc.d
-```
-
-Create rc.d script:
-
-```bash
-sudo bash -c 'cat > /usr/local/etc/rc.d/gitlab_runner' << "EOF"
-#!/bin/sh
-# PROVIDE: gitlab_runner
-# REQUIRE: DAEMON NETWORKING
-# BEFORE:
-# KEYWORD:
-
-. /etc/rc.subr
-
-name="gitlab_runner"
-rcvar="gitlab_runner_enable"
-
-load_rc_config $name
-
-user="gitlab-runner"
-user_home="/home/gitlab-runner"
-command="/usr/local/bin/gitlab-ci-multi-runner run"
-pidfile="/var/run/${name}.pid"
-
-start_cmd="gitlab_runner_start"
-stop_cmd="gitlab_runner_stop"
-status_cmd="gitlab_runner_status"
-
-gitlab_runner_start()
-{
-    export USER=${user}
-    export HOME=${user_home}
-    if checkyesno ${rcvar}; then
-        cd ${user_home}
-        /usr/sbin/daemon -u ${user} -p ${pidfile} ${command} > /var/log/gitlab_runner.log 2>&1
-    fi
-}
-
-gitlab_runner_stop()
-{
-    if [ -f ${pidfile} ]; then
-        kill `cat ${pidfile}`
-    fi
-}
-
-gitlab_runner_status()
-{
-    if [ ! -f ${pidfile} ] || kill -0 `cat ${pidfile}`; then
-        echo "Service ${name} is not running."
-    else
-        echo "${name} appears to be running."
-    fi
-}
-
-run_rc_command $1
-EOF
-```
-
-Make it executable:
-
-```bash
-sudo chmod +x /usr/local/etc/rc.d/gitlab_runner
-```
-
-
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
-
-```bash
-sudo -u gitlab-runner -H /usr/local/bin/gitlab-ci-multi-runner register
-
-Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com):
-
-Please enter the gitlab-ci token for this runner:
-
-Please enter the gitlab-ci description for this runner:
-[name]:
-Please enter the gitlab-ci tags for this runner (comma separated):
-
-Registering runner... succeeded
-Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
-shell
-Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded!
-```
-
-Enable gitlab-runner service and start it:
-
-```bash
-sudo sysrc -f /etc/rc.conf "gitlab_runner_enable=YES"
-sudo service gitlab_runner start
-```
-
-If you don't want to enable gitlab-runner server to restart after reboot, you can start it:
-
-```bash
-sudo service gitlab_runner onestart
-```
-
-**The FreeBSD version is also available from [Bleeding edge](bleeding-edge.md)**
-
-Make sure that you read the [FAQ](../faq/README.md) section which describes
-some of the most common problems with GitLab Runner.
+>**Notes:**
+- The FreeBSD version is also available as a [bleeding edge](bleeding-edge.md)
+  release.
+- Make sure that you read the [FAQ](../faq/README.md) section which describes
+  some of the most common problems with GitLab Runner.
+
+Here are the steps to install and configure GitLab Runner under FreeBSD:
+
+1. Create the `gitlab-runner` user and group:
+
+    ```bash
+    sudo pw group add -n gitlab-runner
+    sudo pw user add -n gitlab-runner -g gitlab-runner -s /usr/local/bin/bash
+    sudo mkdir /home/gitlab-runner
+    sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner
+    ```
+
+1. Download the binary for your system:
+
+    ```bash
+    # For amd64
+    sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-amd64
+
+    # For i386
+    sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-386
+    ```
+
+1. Give it permissions to execute:
+
+    ```bash
+    sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
+    ```
+
+1. Create an empty log file with correct permissions:
+
+    ```bash
+    sudo touch /var/log/gitlab_runner.log && sudo chown gitlab-runner:gitlab-runner /var/log/gitlab_runner.log
+    ```
+
+1. Create the `rc.d` directory in case it doesn't exist:
+
+    ```bash
+    mkdir -p /usr/local/etc/rc.d
+    ```
+
+1. Create the `rc.d` script:
+
+    ```bash
+    sudo bash -c 'cat > /usr/local/etc/rc.d/gitlab_runner' << "EOF"
+    #!/bin/sh
+    # PROVIDE: gitlab_runner
+    # REQUIRE: DAEMON NETWORKING
+    # BEFORE:
+    # KEYWORD:
+
+    . /etc/rc.subr
+
+    name="gitlab_runner"
+    rcvar="gitlab_runner_enable"
+
+    load_rc_config $name
+
+    user="gitlab-runner"
+    user_home="/home/gitlab-runner"
+    command="/usr/local/bin/gitlab-ci-multi-runner run"
+    pidfile="/var/run/${name}.pid"
+
+    start_cmd="gitlab_runner_start"
+    stop_cmd="gitlab_runner_stop"
+    status_cmd="gitlab_runner_status"
+
+    gitlab_runner_start()
+    {
+        export USER=${user}
+        export HOME=${user_home}
+        if checkyesno ${rcvar}; then
+            cd ${user_home}
+            /usr/sbin/daemon -u ${user} -p ${pidfile} ${command} > /var/log/gitlab_runner.log 2>&1
+        fi
+    }
+
+    gitlab_runner_stop()
+    {
+        if [ -f ${pidfile} ]; then
+            kill `cat ${pidfile}`
+        fi
+    }
+
+    gitlab_runner_status()
+    {
+        if [ ! -f ${pidfile} ] || kill -0 `cat ${pidfile}`; then
+            echo "Service ${name} is not running."
+        else
+            echo "${name} appears to be running."
+        fi
+    }
+
+    run_rc_command $1
+    EOF
+    ```
+
+1. Make it executable:
+
+    ```bash
+    sudo chmod +x /usr/local/etc/rc.d/gitlab_runner
+    ```
+1. Register the Runner (look into [runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
+
+    ```bash
+    sudo -u gitlab-runner -H /usr/local/bin/gitlab-ci-multi-runner register
+
+    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com):
+    Please enter the gitlab-ci token for this runner:
+    Please enter the gitlab-ci description for this runner:
+    [name]:
+    Please enter the gitlab-ci tags for this runner (comma separated):
+    Registering runner... succeeded
+    Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
+    shell
+    Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded!
+    ```
+
+1. Enable the `gitlab-runner` service and start it:
+
+    ```bash
+    sudo sysrc -f /etc/rc.conf "gitlab_runner_enable=YES"
+    sudo service gitlab_runner start
+    ```
+
+    If you don't want to enable the `gitlab-runner` service to start after a
+    reboot, use:
+
+    ```bash
+    sudo service gitlab_runner onestart
+    ```
diff --git a/docs/install/index.md b/docs/install/index.md
index 0952337f9cb1e63d0308ce7f265599f4d52c778e..13f4f117e3b35fa16330b53994fc270b53238d62 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -5,11 +5,11 @@ There are three ways to install it. Using Docker, download the binary manually o
 use the repository for rpm/deb packages that GitLab offers. Below you can find
 information on the different installation methods:
 
-- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat (preferred)](linux-repository.md)
+- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat](linux-repository.md) (preferred)
 - [Install on GNU/Linux manually](linux-manually.md)
-- [Install on macOS (preferred)](osx.md)
-- [Install on Windows (preferred)](windows.md)
-- [Install as a Docker Service](docker.md)
+- [Install on macOS](osx.md)
+- [Install on Windows](windows.md)
+- [Install as a Docker service](docker.md)
 - [Install in Auto-scaling mode using Docker machine](autoscaling.md)
 - [Install on FreeBSD](freebsd.md)
 - [Install on Kubernetes](kubernetes.md)
diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md
index 4a88d1b0142378f73129627e1a77553630efd7ab..d7e68c101ed4297cd69ec04b996034b083a47901 100644
--- a/docs/install/kubernetes.md
+++ b/docs/install/kubernetes.md
@@ -1,7 +1,7 @@
-## Run gitlab-runner on a Kubernetes cluster
+# Run GitLab Runner on a Kubernetes cluster
 
 To get started with the GitLab CI Runner on Kubernetes you need to define
-resources that you can then push to the cluster with kubectl.
+resources that you can then push to the cluster with `kubectl`.
 
 A recommended approach to this is to create a `ConfigMap` in Kubernetes such as
 the following:
diff --git a/docs/install/linux-manually.md b/docs/install/linux-manually.md
index 8175e061f1ecf9b135d59a31cf1eb445872942dc..cab7837e885f1cdbf722cd098fbf4055e5105b67 100644
--- a/docs/install/linux-manually.md
+++ b/docs/install/linux-manually.md
@@ -1,6 +1,14 @@
-## Manual installation and configuration
+# Manual installation and configuration on GNU/Linux
 
-### Install
+>**Note:**
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.
+
+If you don't want to use a [deb/rpm repository](linux-repository.md) to install
+GitLab Runner, or your OS is not among the supported ones, you can install it
+manually.
+
+## Install
 
 Simply download one of the binaries for your system:
 
@@ -22,32 +30,33 @@ Optionally, if you want to use Docker, install Docker with:
 curl -sSL https://get.docker.com/ | sh
 ```
 
-Create a GitLab CI user (on Linux):
+Create a GitLab CI user:
 
 ```
 sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
 ```
 
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
+Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
 ```bash
 sudo gitlab-ci-multi-runner register
 ```
 
-Install and run as service (on Linux):
+Install and run as service:
+
 ```bash
 sudo gitlab-ci-multi-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
 sudo gitlab-ci-multi-runner start
 ```
 
-> **Notice**
+>**Note**
+If `gitlab-ci-multi-runner` is installed and run as service (what is described
+in this page), it will run as root, but will execute jobs as user specified by
+the `install` command. This means that some of the job functions like cache and
+artifacts will need to execute `/usr/local/bin/gitlab-ci-multi-runner` command,
+therefore the user under which jobs are run, needs to have access to the executable.
 
->Note that if gitlab-ci-multi-runner is installed and run as service (what is described in this page), 
-it will run as root, but will execute jobs as user specified by the `install` command. This means that some of the 
-job functions like cache and artifacts will need to execute `/usr/local/bin/gitlab-ci-multi-runner` command, therefore
-the user under which jobs are run, needs to have access to the executable.
-
-### Update
+## Update
 
 Stop the service (you need elevated command prompt as before):
 
@@ -55,7 +64,7 @@ Stop the service (you need elevated command prompt as before):
 sudo gitlab-ci-multi-runner stop
 ```
 
-Download the binary to replace runner's executable:
+Download the binary to replace Runner's executable:
 
 ```bash
 sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-linux-386
@@ -73,6 +82,3 @@ Start the service:
 ```bash
 sudo gitlab-ci-multi-runner start
 ```
-
-Make sure that you read the [FAQ](../faq/README.md) section which describes
-some of the most common problems with GitLab Runner.
diff --git a/docs/install/linux-repository.md b/docs/install/linux-repository.md
index 2e1f882f1a2e1e69930e61204d4a49698903babc..dfa807729c976b99df46db0c9763fb10169c7258 100644
--- a/docs/install/linux-repository.md
+++ b/docs/install/linux-repository.md
@@ -1,14 +1,21 @@
-### Install using official GitLab repositories
+# Install GitLab Runner using the official GitLab repositories
 
-Currently we support Debian, Ubuntu, RHEL and CentOS.
+Currently we support:
 
-If you want to use Docker runner, install it before using the multi runner:
+- Debian
+- Ubuntu
+- RHEL
+- CentOS.
+
+If you want to use the [Docker executor], install it before using the Runner:
 
 ```bash
 curl -sSL https://get.docker.com/ | sh
 ```
 
-Add GitLab's official repository via apt-get or yum:
+## Add the repository
+
+Add GitLab's official repository:
 
 ```bash
 # For Debian/Ubuntu
@@ -18,18 +25,18 @@ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-
 curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash
 ```
 
----
-**APT pinning - Debian only**
-
+>**Note:**
+_Debian users should use APT pinning_
+>
 Since Debian Stretch, Debian maintainers added their native package
-with the same name as is used by our package. And by default the official
-repositories will have a priority.
-
+with the same name as is used by our package, and by default the official
+repositories will have a higher priority.
+>
 If you want to use our package you should manually set the source of
 the package. The best would be to add the pinning configuration file.
 Thanks to this every next update of the Runner's package - whether it will
 be done manually or automatically - will be done using the same source:
-
+>
 ```bash
 cat > /etc/apt/preferences.d/pin-gitlab-runner.pref <<EOF
 Explanation: Prefer GitLab provided packages over the Debian native ones
@@ -38,7 +45,6 @@ Pin: origin packages.gitlab.com
 Pin-Priority: 1001
 EOF
 ```
----
 
 Install `gitlab-ci-multi-runner`:
 
@@ -50,7 +56,7 @@ sudo apt-get install gitlab-ci-multi-runner
 sudo yum install gitlab-ci-multi-runner
 ```
 
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
+Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
 ```bash
 sudo gitlab-ci-multi-runner register
@@ -70,12 +76,12 @@ INFO[0037] Runner registered successfully. Feel free to start it, but if it's
 running already the config should be automatically reloaded!
 ```
 
-The runner should be started already and you are ready to build your projects!
+The Runner should be started already and you are ready to build your projects!
 
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
-### Update
+## Update
 
 Simply execute to install latest version:
 
@@ -89,5 +95,9 @@ sudo yum update
 sudo yum install gitlab-ci-multi-runner
 ```
 
-### Manually download packages
-You can manually download the packages from the following URL: https://packages.gitlab.com/runner/gitlab-ci-multi-runner
\ No newline at end of file
+## Manually download packages
+
+You can manually download the packages from the following URL:
+<https://packages.gitlab.com/runner/gitlab-ci-multi-runner>
+
+[docker executor]: ../executors/docker.md
diff --git a/docs/install/osx.md b/docs/install/osx.md
index 319bad953ac029854a9ac7ee2b2904d007988ed0..97262b08d3b23af788fe3d37add1f872c297d8c2 100644
--- a/docs/install/osx.md
+++ b/docs/install/osx.md
@@ -1,90 +1,90 @@
-### Install on OSX
+# Install on macOS
 
-(In the future there will be a brew package).
+In the future there will be a brew package, but for now you have to manually
+download the macOS binary.
 
-Download the binary for your system:
+## Installation
 
-```bash
-sudo curl --output /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
-```
+1. Download the binary for your system:
 
-Give it permissions to execute:
+    ```bash
+    sudo curl --output /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
+    ```
 
-```bash
-sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
-```
+1. Give it permissions to execute:
 
-Get your gitlab-ci token from the *Specific Runners* section on your project 
-settings *Runners* page.
+    ```bash
+    sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
+    ```
 
+**The rest of commands execute as the user who will run the Runner.**
 
-**The rest of commands execute as the user who will run the runner.**
+1. Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
-```bash
-gitlab-ci-multi-runner register
-
-Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
-https://gitlab.com
-Please enter the gitlab-ci token for this runner
-xxx
-Please enter the gitlab-ci description for this runner
-my-runner
-INFO[0034] fcf5c619 Registering runner... succeeded
-Please enter the executor: shell, docker, docker-ssh, ssh?
-docker
-Please enter the Docker image (eg. ruby:2.1):
-ruby:2.1
-INFO[0037] Runner registered successfully. Feel free to start it, but if it's
-running already the config should be automatically reloaded!
-```
+    ```bash
+    gitlab-ci-multi-runner register
 
-Install runner as service and start it:
+    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
+    https://gitlab.com
+    Please enter the gitlab-ci token for this runner
+    xxx
+    Please enter the gitlab-ci description for this runner
+    my-runner
+    INFO[0034] fcf5c619 Registering runner... succeeded
+    Please enter the executor: shell, docker, docker-ssh, ssh?
+    docker
+    Please enter the Docker image (eg. ruby:2.1):
+    ruby:2.1
+    INFO[0037] Runner registered successfully. Feel free to start it, but if it's
+    running already the config should be automatically reloaded!
+    ```
 
-```bash
-cd ~
-gitlab-ci-multi-runner install
-gitlab-ci-multi-runner start
-```
+1. Install the Runner as service and start it:
 
-Voila! Runner is installed and will be run after system reboot.
+    ```bash
+    cd ~
+    gitlab-ci-multi-runner install
+    gitlab-ci-multi-runner start
+    ```
 
-### Update
+Voila! Runner is installed and will be run after a system reboot.
 
-Stop the service:
+## Update
 
-```bash
-gitlab-ci-multi-runner stop
-```
+1. Stop the service:
 
-Download binary to replace runner's executable:
+    ```bash
+    gitlab-ci-multi-runner stop
+    ```
 
-```bash
-curl -o /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
-```
+1. Download the binary to replace the Runner's executable:
 
-Give it permissions to execute:
+    ```bash
+    curl -o /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
+    ```
 
-```bash
-chmod +x /usr/local/bin/gitlab-ci-multi-runner
-```
+1. Give it permissions to execute:
 
-Start the service:
+    ```bash
+    chmod +x /usr/local/bin/gitlab-ci-multi-runner
+    ```
 
-```bash
-gitlab-ci-multi-runner start
-```
+1. Start the service:
+
+    ```bash
+    gitlab-ci-multi-runner start
+    ```
 
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
-### Limitations on OSX
+## Limitations on macOS
 
 >**Note:**
 The service needs to be installed from the Terminal by running its GUI
 interface as your current user. Only then will you be able to manage the service.
 
-Currently, the only proven to work mode for OSX is running service in user-mode.
+Currently, the only proven to work mode for macOS is running service in user-mode.
 
 Since the service will be running only when the user is logged in, you should
 enable auto-login on your OSX machine.
@@ -103,7 +103,7 @@ You can verify that the Runner created the service configuration file after
 executing the `install` command, by checking the
 `~/Library/LaunchAgents/gitlab-runner.plist` file.
 
-### Upgrade the service file
+## Upgrade the service file
 
 In order to upgrade the `LaunchAgent` configuration, you need to uninstall and
 install the service:
diff --git a/docs/install/windows.md b/docs/install/windows.md
index df00ac1cac422455eab12443e8e4dea22d7323a8..21c3f338946404503f914a515d0b1da11848ab50 100644
--- a/docs/install/windows.md
+++ b/docs/install/windows.md
@@ -1,80 +1,88 @@
-### Install on Windows
-
-Create a folder somewhere in your system, ex.: `C:\Multi-Runner`.
-
-Download the binary for [x86][]  or [amd64][] and put it into the folder you
-created.
-
-Run an `Administrator` command prompt ([How to][prompt]). The simplest is to
-write `Command Prompt` in Windows search field, right click and select
-`Run as administrator`. You will be asked to confirm that you want to execute
-the elevated command prompt.
-
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
-
-```bash
-cd C:\Multi-Runner
-gitlab-ci-multi-runner register
-
-Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
-https://gitlab.com
-Please enter the gitlab-ci token for this runner
-xxx
-Please enter the gitlab-ci description for this runner
-my-runner
-INFO[0034] fcf5c619 Registering runner... succeeded
-Please enter the executor: shell, docker, docker-ssh, ssh?
-docker
-Please enter the Docker image (eg. ruby:2.1):
-ruby:2.1
-INFO[0037] Runner registered successfully. Feel free to start it, but if it's
-running already the config should be automatically reloaded!
-```
+# Install on Windows
 
-Install runner as a service and start it. You have to enter a valid password
-for the current user account, because it's required to start the service by Windows:
+To install GitLab Runner on Windows, your user must have a password set up.
 
-```bash
-gitlab-ci-multi-runner install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
-gitlab-ci-multi-runner start
-```
+## Installation
 
-> **Important:** If you encounter an error like '*The account name is invalid*' try to add `.\` before the username.
-> ```shell
-> gitlab-ci-multi-runner install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"
-> ```
+1. Create a folder somewhere in your system, ex.: `C:\Multi-Runner`.
 
-> **Important:** If you encounter a `The service did not start due to a logon failure` error
-> while starting the service, please [look into FAQ](../faq/README.md#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows) to check how to resolve the problem.
+1. Download the binary for [x86][]  or [amd64][] and put it into the folder you
+   created.
 
-> **Notice:** If you don't have a Windows Password, Runner's service won't start. To
-> fix this please read [How to Configure the Service to Start Up with the Built-in System Account](https://support.microsoft.com/en-us/kb/327545#bookmark-6)
-> on Microsoft's support website.
+1. Run an `Administrator` command prompt ([How to][prompt]). The simplest is to
+   write `Command Prompt` in Windows search field, right click and select
+   `Run as administrator`. You will be asked to confirm that you want to execute
+   the elevated command prompt.
 
-Voila! Runner is installed and will be run after system reboot.
+1. Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
-Logs are stored in Windows Event Log.
+    ```bash
+    cd C:\Multi-Runner
+    gitlab-ci-multi-runner register
 
-#### Update
+    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
+    https://gitlab.com
+    Please enter the gitlab-ci token for this runner
+    xxx
+    Please enter the gitlab-ci description for this runner
+    my-runner
+    INFO[0034] fcf5c619 Registering runner... succeeded
+    Please enter the executor: shell, docker, docker-ssh, ssh?
+    docker
+    Please enter the Docker image (eg. ruby:2.1):
+    ruby:2.1
+    INFO[0037] Runner registered successfully. Feel free to start it, but if it's
+    running already the config should be automatically reloaded!
+    ```
 
-Stop service (you need elevated command prompt as before):
+1. Install the Runner as a service and start it. You have to enter a valid password
+   for the current user account, because it's required to start the service by Windows:
 
-```bash
-cd C:\Multi-Runner
-gitlab-ci-multi-runner stop
-```
+    ```bash
+    gitlab-ci-multi-runner install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
+    gitlab-ci-multi-runner start
+    ```
 
-Download the binary for [x86][] or [amd64][] and replace runner's executable.
+    See the [troubleshooting section](#troubleshooting) if you encounter any
+    errors during the Runner installation.
 
-Start service:
+Voila! Runner is installed and will be run after system reboot.
+Logs are stored in Windows Event Log.
 
-```bash
-gitlab-ci-multi-runner start
-```
+## Update
+
+1. Stop the service (you need elevated command prompt as before):
+
+    ```bash
+    cd C:\Multi-Runner
+    gitlab-ci-multi-runner stop
+    ```
+
+1. Download the binary for [x86][] or [amd64][] and replace runner's executable.
+1. Start the service:
+
+    ```bash
+    gitlab-ci-multi-runner start
+    ```
 
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
+## Troubleshooting
+
+If you encounter an error like _The account name is invalid_ try to add `.\` before the username:
+
+```shell
+gitlab-ci-multi-runner install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"
+```
+
+If you encounter a _The service did not start due to a logon failure_ error
+while starting the service, please [look into FAQ](../faq/README.md#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows) to check how to resolve the problem.
+
+If you don't have a Windows Password, Runner's service won't start. To
+fix this please read [How to Configure the Service to Start Up with the Built-in System Account](https://support.microsoft.com/en-us/kb/327545#bookmark-6)
+on Microsoft's support website.
+
 [x86]: https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-windows-386.exe
 [amd64]: https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-windows-amd64.exe
 [prompt]: http://pcsupport.about.com/od/windows-8/a/elevated-command-prompt-windows-8.htm
diff --git a/docs/monitoring/README.md b/docs/monitoring/README.md
index 82715d6ca436c609d1c57e9844056cb63e82a2b7..e45c4177b13c837a9ce489a780578251a10bb5e4 100644
--- a/docs/monitoring/README.md
+++ b/docs/monitoring/README.md
@@ -1,23 +1,25 @@
-# GitLab Runner Monitoring
+# GitLab Runner monitoring
+
+GitLab Runner can be monitored using [Prometheus].
 
 ## Embedded Prometheus metrics
 
 > The embedded HTTP Statistics Server with Prometheus metrics was
 introduced in GitLab Runner 1.8.0.
 
-The GitLab Runner is instrumented with native [Prometheus](https://prometheus.io/)
+The GitLab Runner is instrumented with native Prometheus
 metrics, which can be exposed via an embedded HTTP server on the `/metrics`
 path. The server - if enabled - can be scraped by the Prometheus monitoring
 system or accessed with any other HTTP client.
 
 The exposed information includes:
 
-- runner business logic metrics (e.g. the number of currently running builds)
+- Runner business logic metrics (e.g., the number of currently running builds)
 - Go-specific process metrics (garbage collection stats, goroutines, memstats, etc.)
-- general process metrics (memory usage, cpu usage, file descriptor usage, etc.)
+- general process metrics (memory usage, CPU usage, file descriptor usage, etc.)
 - build version information
 
-The following is an example of the metrics output in Prometheus's
+The following is an example of the metrics output in Prometheus'
 text-based metrics exposition format:
 
 ```
@@ -153,7 +155,7 @@ process_virtual_memory_bytes 3.39746816e+08
 ```
 
 Note that the lines starting with `# HELP` document the meaning of each exposed
-metric. This metrics format is documented in Prometheus's
+metric. This metrics format is documented in Prometheus'
 [Exposition formats](https://prometheus.io/docs/instrumenting/exposition_formats/)
 specification.
 
@@ -186,20 +188,22 @@ the `pprof` HTTP endpoints.
 `pprof` endpoints will be available via an embedded HTTP server on `/debug/pprof/`
 path.
 
-You can read more about using `pprof` in it's [documentation][go-pprof].
+You can read more about using `pprof` in its [documentation][go-pprof].
 
 ## Configuration of the metrics HTTP server
 
+> **Note:**
+The metrics server exports data about the internal state of the
+GitLab Runner process and should not be publicly available!
+
 The metrics HTTP server can be configured in two ways:
 
 - with a `metrics_server` global configuration option in `config.toml` file,
 - with a `--metrics-server` command line option for the `run` command.
 
-In both cases the option accepts a string with the format:
-
-`[host]:<port>`
-
+In both cases the option accepts a string with the format `[host]:<port>`,
 where:
+
 - `host` can be an IP address or a host name,
 - `port` is a valid TCP port or symbolic service name (like `http`).
 
@@ -218,7 +222,5 @@ to a public interface then you should consider to use your firewall to
 limit access to this server or add a HTTP proxy which will add the
 authorization and access control layer.
 
-> **Notice:** Metrics server exports data about internal state of the
-GitLab Runner process and should not be publicly available!
-
-[go-pprof]: https://golang.org/pkg/net/http/pprof/
\ No newline at end of file
+[go-pprof]: https://golang.org/pkg/net/http/pprof/
+[prometheus]: https://prometheus.io
diff --git a/docs/release_process/README.md b/docs/release_process/README.md
index 14edfd6dad082925d9872d80fd229bb6d33531ac..a9701fa986204ddb30690e40a60b4f67859d2147 100644
--- a/docs/release_process/README.md
+++ b/docs/release_process/README.md
@@ -3,22 +3,6 @@
 To handle the growth of this project, in `v1.6` we've introduced a release process correlated
 with GitLab's CE/EE release process.
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [Release roadmap](#release-roadmap)
-  - [Stable release timeline](#stable-release-timeline)
-  - [Supported releases](#supported-releases)
-  - [Release planning](#release-planning)
-- [Workflow, merging and tagging strategy](#workflow-merging-and-tagging-strategy)
-  - [Stable release](#stable-release)
-  - [Patch releases](#patch-releases)
-  - [Branch naming](#branch-naming)
-- [Documentation](#documentation)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Release roadmap
 
 Starting with `v1.4`, GitLab Runner is released on the 22nd day of each month -
diff --git a/docs/shells/README.md b/docs/shells/README.md
index 47a75220c2ff751fe43c735f8f3c4a9557b2ef31..aec3d8d1d91c13617bc3be5aec0196883e6e0763 100644
--- a/docs/shells/README.md
+++ b/docs/shells/README.md
@@ -3,19 +3,6 @@
 GitLab Runner implements a few shell script generators that allow to execute
 builds on different systems.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Sh/Bash shells](#sh-bash-shells)
-- [Windows Batch](#windows-batch)
-- [PowerShell](#powershell)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 The shell scripts contain commands to execute all steps of the build: