some improvements to the writeup