Documenting BizTalk Environment and BizTalk Solution

When it comes to documentation with BizTalk it can be challenging task. What do and what do I not document and how do I document it. In my view there are three types of documentation when it comes to BizTalk in my opinion. That is:

• BizTalk Environment (Design) document
• Functional Design of BizTalk Solution
• Technical (Design) of BizTalk Solution

BizTalk Environment (design) documentation you can described the different BizTalk environment Development, UAT and Production. In this type of document you can roughly describe the following:

• Purpose;
• Design Decisions regarding environments;
• Considerations/Issues;
• Landscape (how does it fit with in IT-Landscape in Enterprise);
• MS BizTalk and SQL Server editions;
• SQL Server configuration (sizing disk, clustering e.a.);
• ICT Policy (Back up, Anti-virus, Patching, e.a.) applied in Enterprise;
• Operating Systems;
• Security Settings;
• Backup and Restore (procedures e.a.);
• BizTalk Group Configuration (clustering, availability e.a.);
• Host configuration;

To add you in documenting the environment or take into consideration (i.e. reference material) is MSDN Microsoft BizTalk Server 2010 Operations Guide.

Functional Design you describe how solution will work, which service it will call, what type of message’s it excepts, processes and sends. You can use notation symbols found in EAI Patterns site and create a functional model for your BizTalk solution (see example below).

 

You can also use UML like state diagram to depict process that is implemented in BizTalk solution (see picture below).

Besides diagrams, you will also document specifications for messages (data types, restrictions, e.a.), security settings, protocols, message patterns, and so on.

Finally Technical (design) documentation of BizTalk solution and its configuration is fairly simple as you use BizTalk documenter for it. This is tool found on codeplex that can automatically generate a document (compiled chm, and even HTML for 2010 version).You can start documenter and following screen will be shown.

Click Next, Select if you want to completely document entire configuration of specific BizTalk application.

Click Next, you can select (this is new with BizTalk 2010 documenter) SSO configuration e.a.

Click Next, choose output options.

Finally you can click Generate Documentation and documentation will generated for you in desired format.

 

As you can see working with documenter is pretty straight forward and type of documentation can be realized with minimal effort. You can keep this documentation easy up to date when changes are made to BizTalk solution. Versioning your solution and its documentation is very important here! Documentation of BizTalk environment will take more effort and will be done in MS Word with perhaps drawings from Visio (there are BizTalk stencils, see post by Sandro). Functional documentation regarding your BizTalk solution will also require some effort, but vital before implementing your solution. Usually MS Word and Visio are used here as well.

Comments are welcome as I am interested in your view on documenting BizTalk.

Cheers!