docs: some improvements

Created by: bartjkdp

This adds some explanation to the documentation and README.md and closes #128 (closed) and closes #136 (closed).