add some narrative docs on the changes