Hi All, I am currently making a concept how to do service documentation at my company. One of the problems is documenting the service contract.
At the moment we use a wiki where we create one page per service with some technical and business documentation. Of course the WSDL is linked the but it only shows the syntax not the semantic. So we additionally document each method and data structure in the wiki. The problem is that the wiki will not notice when the structure of the contract changes so it is quite tedious manual work to keep them in sync. A nice addition we recently did is to refrence the wsdl viewer xslt from tomi vanek in our wsdls (http://tomi.vanek.sk/index.php?page=wsdl-viewer). This formats the wsdl as a web page that you can even show the business people. We could also add documentation elements to the wsdl but this has two problems. The first is that we generate the wsdls out of java code (as it is easier than writing wsdls by hand) and the generation does not support generating documentation. The other and bigger problem is that the dcoumentation in the wsdl is much more difficult to change especially comapred with the ease of use of a wiki. So my question is: How do you document your services? Do you use some clever low tech solutions? Did you write your own kind of repository or do you use a commercial or open source product? Thanks Christian Christian Schneider Informationsverarbeitung Business Solutions Handel und Dispatching Tel : +49-(0)721-63-15482 EnBW Systeme Infrastruktur Support GmbH Sitz der Gesellschaft: Karlsruhe Handelsregister: Amtsgericht Mannheim ‑ HRB 108550 Vorsitzender des Aufsichtsrats: Dr. Bernhard Beck Geschäftsführer: Jochen Adenau, Hans-Günther Meier
