might want to give the documentation handbook a read and see if it inspires any improvements to the README: https://github.com/Clever/dev-handbook/blob/master/documentation.md