Improving timeout behavior and documentation

See #392 
see above