update docs 'for impatient'
improve error reporting