DOC: rewrite from suggestions by neothemachine