improving the docs a bit, closes #1