How much documentation did you get, when you got your Mercedes Car. The stress on Documentation is a little overrated in my humble opinion. If the Tools are made intuitive and the API is made as a natural way of thinking and progression of the state of the Message, The API speaks for itself, and the Developers engagement would be at its peak. If you have to read a Documentation before applying your Brakes on a car, you might as well be too late. Adherence to Standards and not letting unexpected happen and get out of the way of the developers work process is the way to go.
Having said that, If you are on the leading edge of software which no one has attempted before, or trying to create a Market, Thats when your Documentation would explain those edge cases better to gain appreciation of your point of view.
Having said that, If you are on the leading edge of software which no one has attempted before, or trying to create a Market, Thats when your Documentation would explain those edge cases better to gain appreciation of your point of view.