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..
Coding Insomnia 
Leave a Reply