incorporate Bill's notes on documentation