fix docs, port some review comments forward to the new PR
2 files changed