more docs (and formatting fixes)