slightly better docs

CONTRIBUTING.md

@@ -1,16 +1,12 @@
-### Troubleshooting
-
-* Check that all necessary dependencies are installed, including the correct version of Ansible
-* If installing to a local server, use a fresh install of Ubuntu 16.04
-* Check that your issue is not already described in the [troubleshooting](docs/TROUBLESHOOTING.md) docs
-
 ### Filing New Issues
 
-* Please review the [FAQ](https://github.com/trailofbits/algo#faq)
-* Please include the full output from your terminal window if appropriate
-* We only support macOS 10.11+, Windows 8+, and Ubuntu 16.04+
+* Check that your issue is not already described in the [FAQ](https://github.com/trailofbits/algo#faq) or [troubleshooting](docs/TROUBLESHOOTING.md) docs
+* Check that all necessary dependencies are installed, including the correct version of Ansible
+* Algo VPN client supported is limited to only modern operating systems, e.g. macOS 10.11+, iOS 9+, Windows 8+, Ubuntu 16.04+, etc.
+* If your issue has not been resolved by the above, file an issue and fill out the requested information from the Issue Template
 
 ### Pull Requests
 
-* Run [ansible-lint](https://github.com/willthames/ansible-lint) on any new ansible scripts
-* Run [shellcheck](https://github.com/koalaman/shellcheck) on any new shell scripts
+* Run [ansible-lint](https://github.com/willthames/ansible-lint) or [shellcheck](https://github.com/koalaman/shellcheck) on any new scripts
+
+Thanks!

README.md

@@ -2,7 +2,7 @@
 
 [![TravisCI Status](https://travis-ci.org/trailofbits/algo.svg?branch=master)](https://travis-ci.org/trailofbits/algo) [![Slack Status](https://empireslacking.herokuapp.com/badge.svg)](https://empireslacking.herokuapp.com)
 
-Algo VPN (short for "Al Gore", the **V**ice **P**resident of **N**etworks everywhere for [inventing the Internet](https://www.youtube.com/watch?v=BnFJ8cHAlco)) is a set of Ansible scripts that simplifies the setup of a personal IPSEC VPN. It contains the most secure defaults available, works with common cloud providers, and does not require client software on most devices.
+Algo VPN is a set of Ansible scripts that simplifies the setup of a personal IPSEC VPN. It contains the most secure defaults available, works with common cloud providers, and does not require client software on most devices.
 
 ## Features
 
@@ -125,6 +125,10 @@ OpenVPN does not have out-of-the-box client support on any major desktop or mobi
 
 Alpine Linux is not supported out-of-the-box by any major cloud provider. We are interested in supporting Free-, Open-, and HardenedBSD. Follow along or contribute to our BSD support in [this issue](https://github.com/trailofbits/algo/issues/35).
 
+### Where did the name "Algo" come from?
+
+Algo is short for "Al Gore", the **V**ice **P**resident of **N**etworks everywhere for [inventing the Internet](https://www.youtube.com/watch?v=BnFJ8cHAlco).
+
 ## [Troubleshooting](docs/TROUBLESHOOTING.md)
 
 If you have issues deploying and using the Algo VPN server, check the [troubleshooting](docs/TROUBLESHOOTING.md) documentation for solutions to common problems.

docs/Troubleshooting.md

@@ -1,4 +1,11 @@
-### Error: "You have not agreed to the Xcode license agreements"
+## Table of Contents
+
+1. [Error: "You have not agreed to the Xcode license agreements"](#error-you-have-not-agreed-to-the-xcode-license-agreements)
+2. [Error: "fatal error: 'openssl/opensslv.h' file not found"](#error-fatal-error-opensslopensslvh-file-not-found)
+3. [Little Snitch is broken when connected to the VPN](#little-snitch-is-broken-when-connected-to-the-vpn)
+4. [Various websites appear to be offline through the VPN](#various-websites-appear-to-be-offline-through-the-vpn)
+
+### 1. Error: "You have not agreed to the Xcode license agreements"
 
 On macOS, did you try to install the dependencies with pip and encounter the following error?
 
@@ -22,7 +29,7 @@ Storing debug log for failure in /Users/algore/Library/Logs/pip.log
 
 The Xcode compiler is installed but requires you to accept its license agreement prior to using it. Run `xcodebuild -license` to agree and then retry installing the dependencies.
 
-### Error: "fatal error: 'openssl/opensslv.h' file not found"
+### 2. Error: "fatal error: 'openssl/opensslv.h' file not found"
 
 On macOS, did you try to install pycrypto and encounter the following error?
 
@@ -45,10 +52,10 @@ Storing debug log for failure in /Users/algore/Library/Logs/pip.log
 
 You are running an old version of `pip` that cannot build the `pycrypto` dependency. Upgrade to a new version of `pip` by running `sudo pip install -U pip`.
 
-### Little Snitch is broken when connected to the VPN
+### 3. Little Snitch is broken when connected to the VPN
 
 Little Snitch is not compatible with IPSEC VPNs due to a known bug in macOS and there is no solution. The Little Snitch "filter" does not get incoming packets from IPSEC VPNs and, therefore, cannot evaluate any rules over them. Their developers have filed a bug report with Apple but there has been no response. There is nothing they or Algo can do to resolve this problem on their own. You can read more about this problem in [issue #134](https://github.com/trailofbits/algo/issues/134).
 
-### Various websites appear to be offline through the VPN
+### 4. Various websites appear to be offline through the VPN
 
 This issue appears intermittently due to issues with MTU size. If you experience this issue, we recommend filing a ticket for assistance. Advanced users can troubleshoot the correct MTU size by retrying `ping` with the "don't fragment" bit size and decreasing packet size. This will determine the correct MTU size for your network, which you then need to update on your network adapter.