Documenting Web Services 6

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 thoughts on “Documenting Web Services

  1. Benjy May 23,2007 16:35

    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 !!

    cheers
    benjy

  2. Gunnlaugur Briem Jun 21,2007 19:04

    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. 🙂

    Regards,

    – Gulli

  3. anders Jun 23,2007 13:22

    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. Will Nourse Oct 9,2007 18:45

    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. anders Oct 10,2007 09:12

    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. Josh Dec 3,2008 00:12

    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.

Comments are closed.