improve documentation

fixes #1391

and add improvements/fixes to documentation
Actually `n + m` times. I presume this is poor-man's animation (?).