documentation updates, as suggested by akerl_ on HN.