Improve severity docs, fixes #517
Merge pull request #523 from Seldaek/severity_docs

Improve severity docs