moved some documentation around
more docs re error model