Add documentation about linting

README.md

@@ -14,7 +14,7 @@ Read the [project principles](docs/principles.md).
 
 If you publish your prototypes online, they **must** be protected by a [username and password](docs/guides/publishing-on-heroku.md). This is to prevent members of the public finding prototypes and thinking they are real services.
 
-You must protect user privacy at all times, even when using prototypes. Prototypes made with the kit look like GOV.UK, but do not have the same security provisions. Always make sure you are handling user data appropriately. 
+You must protect user privacy at all times, even when using prototypes. Prototypes made with the kit look like GOV.UK, but do not have the same security provisions. Always make sure you are handling user data appropriately.
 
 ## Installation instructions
 
@@ -35,6 +35,7 @@ You must protect user privacy at all times, even when using prototypes. Prototyp
 - [Updating the kit to the latest version](docs/updating-the-kit.md)
 - [Tips and tricks](docs/tips-and-tricks.md)
 - [Creating routes (server-side programming)](docs/creating-routes.md)
+- [Linting](docs/linting.md)
 
 ## Community
 

docs/linting.md

@@ -0,0 +1,33 @@
+# Linting
+
+The prototype kit uses [standardjs](http://standardjs.com/), an opinionated JavaScript linter. All JavaScript files follow its conventions, and it runs on CI to ensure that new pull requests are in line with them.
+
+## Running standard manually
+
+To check the whole codebase, run:
+
+```bash
+npm run lint
+```
+
+## Running standard in your editor
+
+Easier than running standard manually is to install it as a plugin in your editor. There are [guides for most of the popular editors](http://standardjs.com/index.html#text-editor-plugins). This way, it will run automatically while you work, catching errors as they happen on a per-file basis.
+
+## Do I need to respect this?
+
+If you want to submit a pull request to the prototype kit, your code will need to pass the linter.
+
+If you're just using the prototype kit in a separate project, then no, you aren't forced to use standard, or any other linter for that matter. Just write code as you would normally.
+
+## Why lint?
+
+Automated linting ensures project-wide consistency and limits (ideally eliminates) bikeshedding discussions involving spacing, naming conventions, quotes, and others during the pull request review process. It frees the reviewer to focus on the actual substance rather than stylistic issues.
+
+More importantly, linting will catch some low hanging programmer errors, such as calling an undefined function or assigning a value and then never reading it. These allow the programmer to catch some bugs before having to test the code.
+
+## Why standard?
+
+Standard is [widely used (warning: large file)](https://github.com/feross/standard-packages/blob/master/all.json) and has a [good ecosystem of plugins](http://standardjs.com/awesome.html). It's effectively just a preconfigured bundle of eslint, so it can easily be replaced by switching to a generic `.eslintrc` setup.
+
+The core idea of standard is to be opinionated and limit the amount of initial bikeshedding discussions around which linting rules to pick, because in the end, it's not as important which rules you pick as it is to just be consistent about it.