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