updates to spec descriptions and examples

[catkins-miso]

This mostly is just sharpening up the prose in the spec itself, but there was a bad example of RT proposal returning 422 Unprocessable when the proposal was incomplete, which is not the intended semantics of that POST.