notes and docs on updating