improve documentation

This partly reverts c62a44195c82d02f87d5e18db6f86bf191e2c142.