In a recent post entitled Dare responds re: open and closed systems Tim Ewald writes

Responding to my statement:

Dare was quick to blame WSDL and XSD, noting that POX/REST/AJAX systems don't have this problem. Certainly the customers I talk to who have done POX/REST systems are moving toward WSDL and XSD because they want metadata about services in order to facilitate reuse. Without it, they don't have a clear picture of what their systems are doing - or how to reuse them in other contexts. For a closed system, lack of descriptive metadata is fine. But if you want something open and reusable across apps, it really helps to have it

he called me on my description open and closed systems:

Interesting. So Yahoo! Web Services, the Flickr API, Bloglines API, del.icio.us API, and every RSS feed on the planet are closed systems that aren't open and reusable?

Yes, Dare, you are right. I concede that these very public APIs are open and reusable. I was really talking about systems *inside* a company (which I meant to imply with my reference to our customers). In many cases, developers start using POX over HTTP to build systems. When people want to re-purpose those services, its hard because they don't have a lot of information about what message formats and exchange patterns they support. In many cases there is no documentation for that, other than the code and, in that sense, those systems are closed. XSD and WSDL help open them up by providing metadata about what those services do. In some cases that metadata is also useful for finding services that do interesting things. For many of our customers, that is the reason they are migrating from existing POX over HTTP systems to SOAP-based Web services.

As part of my day job I'm in the position of having to work on both internal and external web services at the same time. I can totally see how internal services can end up not being documented well especially since they usually are written for one or two specific partners whose questions can be answered over the phone or email. In fact, I've been meaning to add code samples to one of our specs for over six months but have never gotten around to it because there's always a higher priority issue to work on.

On the other hand, an external web service could be accessed by dozens to hundreds of developers, many of whom will be unable to contact the creators of the service. In this case,  the onus is on the creators to either provide excellent documentation or use standard interfaces that are well documented elsewhere if they actually want anyone to use their service. 

In both situations, I wouldn't consider an XSD or WSDL file as being sufficient documentation. They are definitely better than nothing but they are a far cry from providing enough metadata for users of a service to determine how to properly interact with a service especially when dealing with operations that have to be performed in a series of steps (e.g. uploading a photo or enclosure to a user's home directory then attaching it to a subsequent blog entry).

If your organization is having problems with poorly documented internal services then the answer is to document them NOT to rely on WSDL & XSD files as documentation. As David Ing mentioned in a response to Tim's post   

- XSD/WSDL helps automate the contract side but doesn't really reduce documentation when compared to POX/H, in fact sometimes they increase the complexity up a notch too high. The tools aren't up to a state where you can hook up and just go - staring at the wire and talking on the phone are still facts of life in enterprise integrations. That's a side affect of the problem domain rather than the technology.

In summary, there is no substitute for good documentation. Anyone who tells you otherwise is most likely trying to sell you something.