improved docs and minor fixes