Spotlight on ApexSQL Doc : SQL Server Documentation Tool

Other formatting options

To complete formatting options of your documentation, you can use a custom formatted text that will be displayed on top and bottom of each documentation page. You can also use one or more of the predefined tags as the screenshot shows.

So, now I'm actually through with my description of some of the manifold settings of ApexSQL Doc. I'd like to show you now, what it all was about and how the final result looks like. The tool supports HTML, CHM and HXS (Compiled Help File Format HTML 2.0) as output format. Note, that for using the HXS format, you need to download the compiler separately. It is not included with the tool. That is also the reason why I've "borrowed" the HXS screenshots from the ApexSQL Doc online help.

If you are using Visual Studio 2003 you can get the compiler from here. For Visual Studio 2005 the Help compiler has been integrated into the Visual Studio 2005 SDK which you can download from here. But you might want to check the Visual Studio 2005 Extensibility Center for the lastest version of the SDK. As far as I know, you cannot install the VS 2003 compiler after you've installed Visual Studio 2005.

So, a click on the "Finish" button in the Main Application Window tells ApexSQL Doc to go to work. Depending on the settings you've chosen, this might take some time...

The final documentation

The documentations main HTML screen looks like this:

From there you can navigate and surf to all items of interest, such as tables:

and have a look at how the documentation of a table looks like.

Quite interesting is the "Dictionary" function of the documentation. It allows you to quickly locate all the places where a certain object is used:

In my case, I wanted to see where the column "Num" is used.

Here's an example of the Treeview structure in CHM output format:

A couple of lines above I've mentioned the "Graphical Dependencies" function. Here's how this shows up in the final documentation:

Following the above link, you will see something like this:

Again, I've described the engine in more detail in my paper on the ApexSQL Clean tool, so if you want to read more about it, you can find it here.

Let me finish this section with 2 screenshots from the ApexSQL Doc help that illustrate how the HXS output format looks like:

and

The Command Line Interface

Everything you are able to do via the ApexSQL Doc Gui, you can also do via the Command Line Interface. Meanwhile I've become a huge fan of this functionality in the ApexSQL tools. You can schedule jobs to run such Command Line tasks for off-peak hours and the next morning when you come to the office you have the results ready for examination. One possible purpose I see in our shop for such Command Line documentation jobs are when we push code from the acceptance environment to the production environment. Right after this regularly occurring event, documentation isn't up-to-date anymore and a scheduled documentation task would solve this problem.

Here are some examples of Command Line usage (taken from the ApexSQL Doc Help file):

Documenting database pubs on server CS:
ApexSQLDoc /s:CS /d:pubs

Documenting only tables and views of database tf on server CI:
ApexSQLDoc /s:CI /d:tf /o:12

Loading selection profile and documenting database tf on server CI:
ApexSQLDoc /s:CI /d:tf /i:selection_profile.xml

Creating a CHM file with the name: 10_10_2006.servername.file01.chm
ApexSQLDoc /s:CI /d:northwind /on:{date}.{servername}.file01 /of:chm

Documenting northwind database on server CS displaying the TSQL code highlighted (colorized):
ApexSQLDoc /s:CS /d:northwind /of:chm /oi:h

Documenting northwind database on server CI displaying the Extended Properties:
ApexSQLDoc /s:CI /d:northwind /oi:iep

Documenting pubs database on server CS displaying the following datatype options: DDL, dependencies and properties. ApexSQLDoc /s:CS /d:pubs /dto:dd de pr

Don't worry about the rather cryptic switches. They are all pretty well explained in the products help file.

Conclusion

ApexSQL Doc is the first documentation tool I've ever used and, to be honest, I'm quite amazed at the output it produces. So far documentation to me was printing out some table definitions, probably a diagram and maybe some code for crucial procedures. This, along with some writing thrown in between was documentation to me. And actually I believe I'm not the only one thinking this way. I've been handed out such "documentation" by vendors who did contractual development for us and received a whole lot of money for their work. Now that I know, and actually have seen it myself, that it's quite a breeze to produce sophisticated and complete database documentations, I've massively raised my own level of expectations on future individual software documentations to come.