more documentation, friendlier error messages