include example file in pip package
update installation instructions
add clarifications
better wording