Add documentation on shareable configs and plugins

docs/shareable-configs.md

@@ -0,0 +1,30 @@
+# Shareable Configs
+
+Shareable configs are configurations that you can use and extend from. They can be useful for using the same base configuration in all your projects or for basing your configuration from a well-known one.
+
+To use a shareable config, you have to add it to your SolHint configuration:
+
+```
+  "extends": ["solhint:recommended", "protofire"]
+```
+
+This example shows the two kind of shareable configs that you can use: the ones included with SolHint, that start with `solhint:`, and the ones that you can install from npm. The latter are packages that are prefixed with `solhint-config-`, so in this case the package would be installed doing `npm install solhint-config-protofire` but used as just `protofire` when adding it.
+
+## Creating your own shareable config
+
+Shareable configs are regular npm packages. There are only two confitions:
+
+- The name of the package must start with `solhint-config-`
+- The package must export a regular object with the same structure as a regular configuration object (i.e. the one in your `.solhint.json`).
+
+For example, a very minimal `index.js` in this package could be:
+
+```javascript
+module.exports = {
+  rules: {
+    'max-line-length': 80
+  }
+}
+```
+
+After creating this package you can publish it to npm to make it available for everyone.

docs/writing-plugins.md

@@ -0,0 +1,64 @@
+# Writing plugins
+
+You can write your own plugins to add new rules to SolHint. Plugins are just npm packages that export an array of new rules. A plugin can be as simple as:
+
+```javascript
+module.exports = [MyNewRule]
+```
+
+where `MyNewRule` is a class that implements the rule.
+
+As with shareable configs, there is a convention for the name of these packages: their name has to start with `solhint-plugin-`.
+
+## Structure of a custom rule
+
+A rule is a class that follows two conventions: the constructor accepts a reporter and a config, and `ruleId` field is present in the object. This `ruleId` is the one that will be used to activate and configure the rule. For example:
+
+```javascript
+class MyNewRule {
+  constructor(reporter, config) {
+    this.ruleId = 'my-new-rule'
+
+    this.reporter = reporter
+    this.config = config
+
+    ...
+  }
+```
+
+This is enough for the rule to work but, of course, this will do nothing. Rules are implemented using a visitor pattern: you implement methods that are called when a node in the AST is entered or exited. For example, let's make a rule that forbids naming contracts `Foo`:
+
+```javascript
+class NoFoosAllowed {
+  constructor(reporter, config) {
+    this.ruleId = 'no-foos'
+
+    this.reporter = reporter
+    this.config = config
+  }
+
+  enterContractDefinition(ctx) {
+    const identifier = ctx.children[1]
+    const text = identifier.getText()
+
+    if (text === 'Foo') {
+      this.reporter.error(ctx, this.ruleId, 'Contracts cannot be named "Foo"')
+    }
+  }
+}
+```
+
+_You can see a list of the available AST nodes [here](https://github.com/solidityj/solidity-antlr4/blob/master/Solidity.g4)._
+
+After adding this rule to the exported array, you can publish your package. Remember to prefix the name with `solhint-plugin-`. Let's say our plugin is called `solhint-plugin-naming` and that we already published it and installed it in some project. Then, we can activate this rule in the configuration:
+
+```json
+{
+  "plugins": ["naming"],
+  "rules": {
+    "no-foos": "error"
+  }
+}
+```
+
+And that's it!