Introduction

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.

They are:

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

BizTalk Environment

When it comes down to documenting the BizTalk environment you need to describe overall infrastructure for developer, test, acceptance 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 Setting.
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. There are Visio shapes available you can use for creating a network diagram, see this blog post for resource links.

BizTalk Functional Design

Functional Design you describe how solution will work, which service it will call, what type of message’s it accepts, 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).

Figure 1. EAI Pattern Model (click to enlarge).

The Visio stencil that contains 51 integration pattern icons as Visio shapes can be downloaded from same site through this page. Another notation you can use in functional design is UML (see Notation). Besides diagrams, you will also document specifications for messages (data types, restrictions, and e.a.), security settings, protocols, message patterns, and so on.

BizTalk Technical Design

Finally Technical (design) documentation of BizTalk solution and its configuration is can be fairly simple as you use BizTalk documenter for it. The documenter tool makes it easier for you to document BizTalk 2010 installations and compiles the following:

BizTalk Server Host Configuration
Send / Receive port configuration
Orchestration diagrams complete with any custom code
Schema and Map content
Pipeline process flow
Adapter configuration
Rule engine vocabularies and policies

The documenter can output the information in a help files or Word. 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.

Notation

The Business Process Modeling Notation (BPMN) is a graphical notation that defines the steps in a business process. BPMN can be used to model an orchestration in Visio. BPMN is a standard set of diagramming conventions for describing business processes. It is designed to visualize a rich set of process flow semantics within a business process and the communication between independent processes.

Another notation that can be used for BizTalk documentation is UML. Unified Modeling Language (UML) is a standardized general-purpose modeling language in the field of object-oriented software engineering. You can create a sequence diagram (one of UML interaction diagrams) to depict process that is implemented in BizTalk solution.