DOC some improvements as suggested by @ogrisel