update the readme with some notes
include a glossary  in the appendix
make some readme updates more readable