many minor doc updates and tiny refactorings