more docs modifications following reviews