docs modifications following cvan's review