Documenting Web Services

I’m now trying to do what really should be very core to any enterprise that is serious about using SOA and web services – making sure that there is an easy way to document your services and to keep that documentation available and updated. Well, it has turned out to be much more painful than I would have imagined. Our policy on documentation is something like “there’s no point in doing it if no-one will ever read/use it”. So in order for a documentation solution to be accepted all of these points must be fulfilled:

  • The documentation must be easy to distribute. I’m guessing the only way is to create some sort of web site with all docs.
  • Easy to keep updated. In practice that means the documentation must be written inside the dev environment, preferably as code comments.
  • Organized/Categorized in a relevant way. You shouldn’t have to know in advance which service to use.

As you probably know, I’ve been playing around with Sandcastle. But there are a couple of problems with it. First of all, there’s no built-in support for generating a nice web site. It is however possible with third-party extensions such as Eric Woodruff’s Sandcastle Help File Builder (an excellent tool by the way) so I guess that part is good enough. The biggest problem is that I don’t know where to keep the documentation..! Sandcastle is mostly used for building docs for class libraries, not web sites. In fact, a Web Site project in Visual Studio 2005 doesn’t even let you generate a documentation XML.. I’m considering doing it like the MapPoint Web Service SDK, i.e. generating a client proxy with wsdl.exe and documenting that. But what happens when something changes? I won’t be able to regenerate the proxy since I’d loose all documentation.

The best bet so far is probably from an article I found on Code Project about how to put your web service documentation in an external file but still have it rendered by navigating to the .asmx file. Problem here is that the documentation still is in a file that isn’t linked to the actual code. Maybe I could generate that XML file using Sandcastle..

Oh well… It’s Friday.. I’ll figure this out next week.. maybe..

6 responses to “Documenting Web Services”

  1. hi, just got to read your blog today and so theres two comments coming bunched together (WSSF and this one) … the codeproject article is very old, but it does hint at the essential aspect of webservice documentation namely the WSDL is the soul of it. of course, with advanced webservices when you have policy files and all that, WSDL wont be enough, but its a start. This actually makes a strong case for a tool like WSSF V3 where the visual modelling can be used to generate documentation as well. In terms of sandcastle, i dont know much about it yet, but maybe some XSL that works on the interim XML (that goes into the CHM) might be usable to put data on the site? it does look like you want to codegen an entire website !!



  2. Hi,

    have you looked into this any further? I’m starting to work on the same thing, trying to set up webservice documentation generation and make it as automated as possible, and am first scouting around for the already-solved parts. 🙂


    - Gulli


  3. I’m afraid I still haven’t found a good solution. With a bit of luck I’ll be able to spend a day or two on this the next couple of weeks.


  4. Hi – just found this and am running into the same issue. Started down the Sandcastle route, but I don’t think that’s really going to cut it for now. Wondering if you have made any progress?


  5. I started out building a wrapper around Microsoft UDDI services that was more tailored to the way we work (and that would be able to hold the documentation). Unfortunately, I wasn’t able to spend enough time on it. Still, it was looking promising so I might revisit it when the work-load decreases a bit.


  6. Ever come up with a way to document web services from WSDL to HTML using Sandcastle or similar automated means? A WSDL to UML diagram tool would be nice as well.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

About Me

Consultant, Solution Architect, Developer.

Do note that this blog is very, very old. Please consider that before you follow any of the advice in here!


%d bloggers like this: