add troubleshooting guide and link on the index page

README.md

@@ -58,6 +58,8 @@ NODE_ENV=development node index.js
 
 See [development instructions](#development) for more information about running locally (and restarting automatically when files change).
 
+If you run into problems, check the [troubleshooting][troubleshooting guide]. 
+
 
 Configurations
 --------------
@@ -148,6 +150,7 @@ Copyright © 2013–2016, Springer Nature
 [sidekick-proposal]: https://github.com/pa11y/sidekick/blob/master/PROPOSAL.md
 [travis]: https://travis-ci.org/pa11y/dashboard
 [travis-img]: https://travis-ci.org/pa11y/dashboard.png?branch=master
+[troubleshooting]: https://github.com/pa11y/dashboard/blob/master/TROUBLESHOOTING.md
 
 [info-license]: LICENSE
 [info-node]: package.json

TROUBLESHOOTING.md

@@ -0,0 +1,27 @@
+Troubleshooting
+===============
+
+
+Common issues
+-----
+
+* `500` errors or `Could not connect to pa11y-webservice` messages are often related to MongoDB. Ensure that you have the [mongo-install][latest version of MongoDB] installed, and that it's running - it doesn't always start automatically. 
+* Error messages saying that pa11y-webservice isn't running may be due to dependency installation problems. Try deleting your `pa11y-dashboard/node_modules` directory and running `npm install` again. 
+
+
+Check to see if the issue has been reported
+-----
+
+* Check the [issues][issue tracker] for similar issues.
+
+
+Create an issue
+-----
+
+If all else fails, [create-issue][create an issue] and we'll help you. Please include your node.js, Phantom, and MongoDB version numbers, and your operating system. 
+
+
+[issues]: https://github.com/pa11y/dashboard/issues?utf8=%E2%9C%93&q=is%3Aissue
+[mongo-install]: https://docs.mongodb.org/manual/installation/
+[create-issue]: https://github.com/pa11y/dashboard/issues/new
+