documentation

copy edits to clarify error handling