big improvements to the writeup