Documenting Web Services

Dec 10, 2008 at 5:45 PM
I am documenting a pair of web services that are to be used in concert with one another to implement a distributed application. In the SDK, I need to document these web services in a manner that is agnostic as to whether the reader is implementing a client or a server, as they will have to implement both. The web services are described by a pair of WSDLs and the input and output messages are described in various XSDs. We've tried generating managed reference docs off of the proxy classes created by svcutil using Sandcastle but the docs produced are less than ideal. Is there a standard for documenting web services from both the bottom up and top down perspectives and does sandcastle support it or am I in pretty much uncharted waters here?
Dec 10, 2008 at 6:39 PM

I haven't heard of any presentation styles or build components for Sandcastle that will generate documentation for WSDL or XSD.  But it would certainly be possible for somebody to write one (time permitting ;).  You may want to add a feature request to the Sandcastle project or maybe even to the Sandcastle Styles project.

What exactly about the reference documentation that is generated from the proxy is "less than ideal"?

I think most developers will find it useful having a high-level view of the contracts (classes) and behaviors (methods) that are offered by your service, regardless of whether they are responsible for writing code that communicates with it (client) or writing code that implements it (server).

In my experience I rarely need to know anything at all about third-party services' WSDLs and XSDs, so having that information would not be as useful as having managed referenced documentation that describes the service in terms of the proxy classes that are automatically generated for me by svcutil.  And If I was responsible for implementing one of the services, I'd probably start by generating the foundation using svcutil; therefore, the documentation would still apply.

For non-managed code, however, I know that sometimes working with web services may require a more intimate knowledge of the contracts and messages since the tools to automatically generate proxies for the platform might not exist or they may not be as self-sufficient as .NET tools.  Is your requirement to support non-managed code?

- Dave
Dec 10, 2008 at 6:57 PM
I was hoping to produce platform neutral web services documentation. The API is pretty simple so showing classes, properties, methods, etc... is not really useful. What would be ideal would be for the docs to describe the services and the input and output messages which are the simple and complex types described in the XSDs.