Contracts start with documentation

I just got back from TechEd and had a chance to catch up on posts, including Dare's recent follow up to my last post about contracts and metadata. He points out that WSDL/XSD is no substitute for good documentation and I totally agree. In fact, this was kind of a theme at the BOF on contracts that Aaron and I hosted in Orlando. A contract is an agreement expressed in a number of ways. First and foremost, there is at least a prose document - “the Word doc” - for want of a better term. Some aspects of what the Word doc says are captured in machine-consumable form (XSD, WSDL, WS-Policy, XSLT, etc), but many are not. We should never mistake those expressions of our contract for the contract itself.

Posted Jun 09 2005, 04:07 PM by tim-ewald

Comments

Buddhike de Silva wrote re: Contracts start with documentation
on 06-16-2005 3:09 PM
Watch this ;-).
http://weblogs.asp.net/cweyer/archive/2005/06/15/413155.aspx
Scott Hanselman wrote re: Contracts start with documentation
on 07-21-2005 5:00 PM
I like to split the difference and fill my documentation elements with prose then generate a big word doc from the WSDL. The angle brackets are authoritative and the Word DOC is a build artifact.

Add a Comment

(required)  
(optional)
(required)  
Remember Me?