rearranges the readme and adds some more contextual info to the examples