add intro to documentation and improve Makefile