Refactor docs

docs/faq/README.md

@@ -128,30 +128,39 @@ See [an example of a user issue][1105].
 [recipes]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server
 [1105]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/issues/1105
 
-## 11. Runner cannot be installed on OSX, because of `"launchctl" failed: exit status 112, Could not find domain for`:
+## 11. `"launchctl" failed: exit status 112, Could not find domain for`
 
-Make sure that you manage GitLab Runner service from the GUI Terminal application, not the SSH connection.
+This message may occur when you try to install GitLab Runner on OSX. Make sure
+that you manage GitLab Runner service from the GUI Terminal application, not
+the SSH connection.
 
-## 12. Runner is stuck on `Failed to authorize rights (0x1) with status: -60007.` when using OSX:
+## 12. `Failed to authorize rights (0x1) with status: -60007.`
 
-There are two problems why this happens:
-1. Make sure that your user can do UI interactions.
+If your Runner is stuck on the above message when using OSX, there are two
+problems why this happens:
 
-    ```
+1. Make sure that your user can perform UI interactions:
+
+    ```bash
     DevToolsSecurity -enable
     sudo security authorizationdb remove system.privilege.taskport is-developer
     ```
-    
+
     The first command enables access to developer tools for your user.
-    
-    Second command allows the user, member of developer group to do UI interactions, ex. run iOS simulator.
+    The second command allows the user who is member of the developer group to
+    do UI interactions, e.g., run the iOS simulator.
+
+    ---
 
-2. Make sure that your runner service doesn't use `SessionCreate = true`.
-Previously when running GitLab Runner as an service we were creating the `LaunchAgents` with `SessionCreate`.
-At that point (`Mavericks`) it was the only solution to make Code Signing work,
-but recently with introduction of `El Capitan` OSX introduced a lot of new security features which did change this behaviour.
-Since GitLab Runner 1.1 when creating a `LaunchAgent` we don't set the `SessionCreate`.
-However, in order to upgrade you need to manually reinstall the `LaunchAgent` script:
+2. Make sure that your Runner service doesn't use `SessionCreate = true`.
+   Previously, when running GitLab Runner as a service, we were creating
+   `LaunchAgents` with `SessionCreate`. At that point (**Mavericks**), this was
+   the only solution to make Code Signing work. That changed recently with
+   **OSX El Capitan** which introduced a lot of new security features that
+   altered this behavior.
+   Since GitLab Runner 1.1, when creating a `LaunchAgent`, we don't set
+   `SessionCreate`. However, in order to upgrade, you need to manually
+   reinstall the `LaunchAgent` script:
 
     ```
     gitlab-ci-multi-runner uninstall
@@ -159,4 +168,5 @@ However, in order to upgrade you need to manually reinstall the `LaunchAgent` sc
     gitlab-ci-multi-runner start
     ```
 
-    Then you can verify that `~/Library/LaunchAgents/gitlab-runner.plist` have `SessionCreate` set to `false`.
+    Then you can verify that `~/Library/LaunchAgents/gitlab-runner.plist` has
+    `SessionCreate` set to `false`.

docs/install/docker.md

@@ -62,7 +62,8 @@ running already the config should be automatically reloaded!
 
 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 most common problems with the GitLab Runner. 
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.
 
 ### Update
 
@@ -114,7 +115,7 @@ gitlab/gitlab-runner    latest              3e8077e209f5        13 hours ago
 gitlab/gitlab-runner    alpine              7c431ac8f30f        13 hours ago        25.98 MB
 ```
 
-**Alpine Linux image is designed to use only Docker as the method of spawning runners.** 
+**Alpine Linux image is designed to use only Docker as the method of spawning runners.**
 
 The original `gitlab/gitlab-runner:latest` is based on Ubuntu 14.04 LTS.
 
@@ -138,6 +139,6 @@ Install the `selinux-dockersock` and to resolve the issue: https://github.com/dp
       -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
       gitlab/gitlab-runner:latest
 ```
-      
+
 More information about the cause and resolution can be found here:
 http://www.projectatomic.io/blog/2015/06/using-volumes-with-docker-can-cause-problems-with-selinux/

docs/install/freebsd.md

@@ -24,7 +24,7 @@ Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/ci):
 Please enter the gitlab-ci token for this runner:
 
 Please enter the gitlab-ci description for this runner:
-[name]: 
+[name]:
 Please enter the gitlab-ci tags for this runner (comma separated):
 
 Registering runner... succeeded
@@ -43,5 +43,6 @@ gitlab-ci-multi-runner run
 Voila! Runner is currently running, but it will not start automatically after system reboot because BSD startup service is not supported.
 
 **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 most common problems with the GitLab Runner. 
+
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.

docs/install/linux-manually.md

@@ -67,4 +67,5 @@ Start the service:
 sudo gitlab-ci-multi-runner start
 ```
 
-Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. 
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.

docs/install/linux-repository.md

@@ -50,7 +50,8 @@ running already the config should be automatically reloaded!
 
 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 most common problems with the GitLab Runner. 
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.
 
 ### Update
 

docs/install/osx.md

@@ -71,32 +71,40 @@ Start the service:
 gitlab-ci-multi-runner start
 ```
 
-Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. 
+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
 
-Currently the only proven to work mode for OSX is running service in user-mode.
+>**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.
 
-**The service needs to be installed from Terminal running GUI interface as your user.
-Only then you will be able to manage the service.**
+Currently, the only proven to work mode for OSX is running service in user-mode.
 
-Since the service will be running only when the user is logged in you should enable auto-logging on your OSX machine.
+Since the service will be running only when the user is logged in, you should
+enable auto-logging on your OSX machine.
 
-The service will be launched as one of `LaunchAgents`.
-By using `LaunchAgents` the builds will be able to do UI interactions,
-making it possible to run and test on iOS simulator and also do process instrumentations.
+The service will be launched as one of `LaunchAgents`. By using `LaunchAgents`,
+the builds will be able to do UI interactions, making it possible to run and
+test on the iOS simulator.
 
-Worth to note is that OSX also have the `LaunchDaemons`, the services running completely in background.
-The `LaunchDaemons` are run on system startup, but they don't have the same access to UI interactions as `LaunchAgents`.
-You can try to run service as `LaunchDaemon`, but this mode of operation as of now is not supported.
+It's worth noting that OSX also has `LaunchDaemons`, the services running
+completely in background. `LaunchDaemons` are run on system startup, but they
+don't have the same access to UI interactions as `LaunchAgents`. You can try to
+run the Runner's service as `LaunchDaemon`, but this mode of operation is not
+currently supported.
 
-You can verify that runner created service configuration after the executing `install` command
-by checking the `~user/Library/LaunchAgents/gitlab-runner.plist` file.
+You can verify that the Runner created the service configuration file after
+executing the `install` command, by checking the
+`~user/Library/LaunchAgents/gitlab-runner.plist` file.
 
 ### Upgrade the service file
 
-In order to upgrade the `LaunchAgent` configuration you need to uninstall and install the service:
-```
+In order to upgrade the `LaunchAgent` configuration, you need to uninstall and
+install the service:
+
+```bash
 gitlab-ci-multi-runner uninstall
 gitlab-ci-multi-runner install
 gitlab-ci-multi-runner start

docs/install/windows.md

@@ -60,7 +60,8 @@ Start service:
 gitlab-ci-multi-runner start
 ```
 
-Make sure that you read the [FAQ](../faq/README.md) section which describes most common problems with the GitLab Runner. 
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.
 
 [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