Document type of errors

We have the following severities errors:
```
severities = {
    CRITICAL : 'CRITICAL',
    ERROR : 'ERROR',
    WARNING : 'WARNING',
    INFO : 'INFO',
    DEBUG : 'DEBUG',
    NOTSET : 'NOTSET'
}
```
We need to document on what type/kind of error fall into which error severities, perhaps in the SPEC