documentation fixes
document and clean up responsibilities