edit writeup, refactor and housekeeping