BizTalk Documenter: A Proven Documentation Tool
The BizTalk Documenter has been available for many years and across multiple BizTalk versions, starting with BizTalk Server 2004 up to BizTalk Server 2016.
For me, it remains my favorite documentation tool.
In fact, I strongly believe that if every product included a similar tool for generating technical documentation, overall documentation quality would improve significantly.
📝 One-Minute Brief
One-Minute Brief (TL;DR):
However, the default cover page is quite simple and looks old-fashioned:
Why CHM Still Matters
BizTalk Documenter generates documentation in CHM format, which is based on the HTML Help 1.0 specification. This format is old and dates back to around 1997, when Internet Explorer 4 was introduced.
However, despite its age, CHM remains popular. The reason is simple: it is easy to generate using plain HTML, highly interactive, and works out of the box on most Windows platforms.
Customizing Documentation Per Client
Over the years, I’ve made a habit of personalizing documentation for each client.
For example, I often customize:
- The client’s logo and name on the cover.
- The color scheme matches corporate branding.
- A custom cover image, when appropriate.
As a result, a common question naturally arises.
Can We Customize the BizTalk Documenter Cover Page?
The answer is straightforward: yes, absolutely.
I’ve been doing this for my clients for a long time. Still, this post also serves as a personal reminder. Each time I start working with a new client, I tend to run into the same challenges.
Common Challenges I Keep Facing
Typically, I find myself:
- Forgetting how the customization works
- Wondering which resources are required and whether they are mandatory
- Spending too much time formatting HTML to meet my requirements
Why Existing Guides Fall Short
To be clear, several blog posts already explain how to customize the BizTalk Documenter cover page.
However, most of them miss a key point.
They usually don’t provide downloadable resources that you can:
- Use directly as a template
- Easily modify images, colors, and layout
- Reuse as inspiration, a tutorial, or a working sample
That gap is exactly what this post aims to address.
How to customize the BizTalk Documenter cover page
What is really necessary to transform your cover page from the default one presented in the picture above to something like this:
That contains:
- 1- Logotype of BizTalk Server version.
- 2- Header title and subtitle.
- That can be your platform code name, like <client name> ESB.
- 3- Logotype of the client organization.
- 4- Name of the documentation.
- 5- Other pictures, for example, project logotype.
- 6- Disclaimer.
- 7- background color.
- 8- Copyright.
Or something like this with a background picture:
And in fact, this is quite a simple task. Fortunately for us, BizTalk Documenter allows us to specify a Resource Folder on the Output Options screen:
For the sake of simplicity, let’s call it Resources (but it can be other as you see in the picture Resource V1). In the root of this folder, you should:
- Add a custom HTM page that. You mandatory need to called it: titlePage.htm.
- If you give it another name, it will not work. The file will be ignored, and the
default cover will be generated.
- If you give it another name, it will not work. The file will be ignored, and the
- And you should, once again, for the sake of simplicity, add all the necessary
picture files to the folder or sub-folder.
This is the content/aspect of my titlePage.htm file for the first sample, provide it here:
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<TITLE>BizTalk Configuration</TITLE>
<LINK href="CommenTReport.css" type="text/css" rel="stylesheet"/>
</HEAD>
<BODY style="background-color:#7FB4C4; PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;">
<TABLE cellspacing="0" width="100%" height="100%">
<TR bgcolor="#0072C6">
<TD style="PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;">
<IMG SRC="bts.png"/>
</TD>
<TD width="100%">
<p style="COLOR:#FFFFFF;TEXT-ALIGN:left;FONT-FAMILY:Calibri,Verdana, Arial, sans-serif;FONT-SIZE:40;"><b>BizTalk Server 2016</b><br>Solution Technical Documentation</p>
</TD>
<TD align="right" style="PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;">
<IMG SRC="logotype.png"/>
</TD>
</TR>
<TR>
<TD colspan="3" height="150">
<BR/>
<BR/>
<BR/>
</TD>
</TR>
<TR style="background-color: #0072C6;">
<TD colspan="2" style="PADDING-LEFT:20px; PADDING-RIGHT:20px;">
<BR/>
<BR/>
<BR/>
<SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:18;FONT-WEIGHT:bold;PADDING-LEFT:5px;PADDING-RIGHT:5px;">Name: #APPLICATION#</SPAN>
<BR/>
<BR/>
<SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:18;FONT-WEIGHT:bold;PADDING-LEFT:5px;PADDING-RIGHT:5px;">Installation Server: #SERVER#</SPAN>
<BR/>
<SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:18;FONT-WEIGHT:bold;PADDING-LEFT:5px;PADDING-RIGHT:5px;">Installation Database: #DATABASE#</SPAN>
<BR/>
<BR/>
<BR/>
<BR/>
<SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:11;">All information in this document is confidential and for Sandro Pereira exclusive access. Access to this document by any other entity is not permitted without prior permission.</SPAN>
<BR/>
<SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:11;">Any entity with access to this document is bound by its confidentiality.</SPAN>
<BR/>
<BR/>
<BR/>
</TD>
<TD style="PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;">
<IMG SRC="documentation.png"/>
</TD>
</TR>
<TR>
<TD colspan="3" height="100%">
<BR/>
<BR/>
<BR/>
</TD>
</TR>
<TR>
<TD colspan="3" align="right">
<P style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:10;">Generated on: #GENDATE#<BR/>Copyright © Sandro Pereira 2019</P>
</TD>
</TR>
</TABLE>
</BODY>
</HTML>
Download
THIS RESOURCE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND.
You can download the BizTalk Documenter tool: Cover Customization Resources from GitHub here:
Hope you find this helpful! If you liked the content or found it useful and would like to support me in writing more, consider buying (or helping to buy) a Star Wars Lego set for my son.
It is quite powerful tool but crashes on our side… I cannot select “Document entire configuration” but has to select a few in order for it to work. in worst case 2 applications / run….I have no idea what causes this…complex applications?