[blater]

Are you doing model driven development for the contract - building the contract artifacts first (e.g. the wsdl/wadl/whatever) and generating documentation and some of the code off them? If you can then the documentation problem goes away. You just regenerate the docs from the contract as part of the build.

Mocking takes time but means other teams can develop against your API before you've written any code, so while your coding effort is a little more, the elapsed development time across all teams is shorter. That can be a big win.