update docs to recent changes in binary-data

also, clear up some of the documentation