Sunday, March 13, 2005

BizTalk Configuration Documenter

As promised, a few thoughts on the above utility.

First impressions are great. It produces a fantastic-looking output, using the "Description" metadata properties of orchestrations and ports to provide the detail. It even includes the diagrams of the orchestrations - how does it do that (same way as the debugger and tracking and profile editor I guess - is it some graphics API)?

I have a couple of gripes - one being that it documents external web reference schema, which can swamp the documentation with content that is not strictly relevant.

On a broader note, it provides the sort of documentation that is actually useful. If you extend the raw output by adding in custom HTML introduction pages you can generate documentation that would make any SDK developer proud. My friend and ex-colleague James, as a certified SCRUM Master, would I'm sure agree that less documentation is more, and specifically that documentation generated from source code (or source diagrams, in the BizTalk realm) is the most powerful technical documentation of all. Functional specifications are of course extremely valuable in defining how an application should behave, but should be written without regard to the implemented technology, IMHO.

I am fed up with a.) reading, and b.) being asked to write, documentation that includes database table desciptions in Word documents. They are worthless, and invariably obselete the minute they are committed to paper.

People who need to know about a database schema should be able to read a schema diagram, ditto object models. Most source applications (e.g. Oracle, SQL Server, VS.NET, Java) can now be documented using tools that use introspection to determine datatypes, interrelationships etc. The missing information, namely a broader description of the 'problem domain' that the code addresses, can be added in a separate, simple, overview document. And if the documentation tool produces compiled HTML help files (as this utility does), then this overview documentation can be integrated with the technical documentation, if that's desirable.

Let's just have a more intelligent approach to documentation, and specifically an acknowledgement that detailed technical documentation serves a very different purpose from its functional / project proposal equivalents.

No comments: