doc improvements suggested by @bobef