Improve documentation

Fix #162
Work on #225

Close #226

docs/developer-guide/events/list-of-events.md → docs/developer-guide/collectors/events.md

@@ -1,4 +1,4 @@
-# List of events emitted by a collector
+# Events
 
 `collector`s communicate via events. The following is a list of all
 the events common to all `collector`s, with their signature, and the

docs/developer-guide/collectors/index.md

@@ -1 +1,12 @@
-# Collectors
+# How to develop a collector
+
+A collector needs to implement at least [this list of events](./events.md).
+
+> More info needed
+
+## How to test a collector
+
+To facilitate the task, we've created a test suite with the minimum functionality
+a `collector` needs to implement.
+
+> More info needed

docs/developer-guide/formatters/index.md

@@ -0,0 +1,56 @@
+# How to develop a formatter
+
+You just need to create a module that exports an object with a method named
+`format()`. This method will receive an array of `message`s if any issues
+have been found.
+
+The following is a basic `formatter` that just `.stringify()` the array
+into the console:
+
+```js
+const formatter = {
+    format(messages) {
+        console.log(JSON.stringify(messages, null, 2));
+    }
+};
+
+export default formatter;
+```
+
+A `message` looks like this:
+
+```json
+{
+    "resource": "string", // The url or name of the asset with the issue
+    "line": "number", // The line number where the issue was found if applicable
+    "column": "number", // The column number where the issue was found if applicable
+    "severity": "number", // 1 (warning), 2 (error)
+    "message": "string" // The human friendly detail of the error
+}
+```
+
+With this, you can group the issues by `resource` and sort them by `line` and
+`column`. Using the previous example and `lodash` will look as follows:
+
+```js
+import * as _ from 'lodash';
+
+const formatter = {
+    /** Format the problems grouped by `resource` name and sorted by line and column number */
+    format(messages) {
+        const resources = _.groupBy(messages, 'resource');
+
+        _.forEach(resources, (msgs, resource) => {
+            const sortedMessages = _.sortBy(msgs, ['line', 'column']);
+
+            console.log(`${resource}: ${msgs.length} issues`);
+            console.log(JSON.stringify(sortedMessages, null, 2));
+        });
+    }
+};
+
+export default formatter;
+```
+
+You can always check the code of any of the official `formatter`s for more
+complex scenarios.

docs/developer-guide/index.md

@@ -1 +1,22 @@
 # Developer guide
+
+Sonar was designed with extensibility in mind. There are 3 main concepts that a
+developer needs to know about:
+
+* `rule`: Is a test that is run on an asset (website, HTML file, image,
+  request, etc.). E.g.: Verify that the HTML document has a valid language
+  declared.
+* `collector`: It is the way in which sonar obtains information about the DOM,
+  requests, assets, etc. The underlying technique (debugging protocol, web driver,
+  etc.) to access this data does not matter to the rest of the system.
+* `formatter`: Transforms the results into something useful to the user. It could
+  be as simple as printing out the results in the command line, or something more
+  complex like creating an HTML report.
+
+Any developer can create their own `rule`s, `collector`s, and/or `formatter`s and
+use them without having to do a Pull Request to the main project. They can even
+be distributed as [`npm`](https://www.npmjs.com/) packages.
+
+Even though sonar is developed using [TypeScript](https://www.typescriptlang.org/),
+there is no need for it if you are writting your own `rule`, `collector` or
+`formatter`. Just follow the examples for each area and you should be good.