Introduction
Real programmers don’t document their code.
This and many other phrases, one can hear when it comes to documentation. And if you’re really serious about making life of your co-workers, clients, and anyone else who will maybe read your code, harder than it already is, take your time and read carefully through this ultimate step-by-step guide How to write unmaintainable code
While you shouldn’t take the above too seriously, there seems to be some truth in that developer and documentations are natural enemies. Be that documentation of the code itself or documentation about some application. I have seen quite a few documents written by developers that were supposed to be handed to the customers as some sort of manual or reference material. Many times, though certainly not always, you can nothing but agree with C.J. Date: “Good writing DOES matter!” The lack of precision in many technical writings is significant. Fortunately the metadata of an SQL Server database cannot be imprecise. So, at least documenting a database isn’t subject to imprecision when one refers only to the databases’ metadata and now one only needs time to actually do this job. But why spend more time on it than is absolutely necessary? The purpose of this paper is to show you, how ApexSQL Doc can make your life a little bit easier (at least with respect to that unwanted task of documentation) and save you a lot of time that you can spend more effectively otherwise. And I’m quite sure that you agree with me that every single hour spend less on documentation is worth almost every effort. Challenging question, hm? 😉 Of course, there are tons and tons of possible valid answers to this question: Fact is that almost everything we do needs to be documented, either because one wants to keep such things for ones own purposes, or because someone in the food chain above us ask us to do so. My personal favourites in that respect are internal auditors, btw. Each time our department had such an internal audition we ended up documenting more things less people are actually interested in. I guess this probably sounds kind of familiar to one or two readers of this paper, but that is another endless story anyway. Now for something completely different… As with all other ApexSQL tools, you can visit the ApexSQL homepage at http://www.apexsql.com/ and download a fully functional 30 days evaluation copy of their Doc tool. The download is just about 8 MB in size, so manageable even with a slower internet connection. Installation itself is just a matter of minutes.
The system requirements for ApexSQL Doc are as follows:Purpose
Why to document anyway?
Installation, System Requirements, supported SQL Server versions
|
Software: |
ADO 2.8 (or higher) |
|
Operating System: |
Windows 2000 |
|
CPU: |
PC at 450 MHz (or faster). Pentium III recommended |
|
RAM: |
256 MB RAM (512 RAM recommended) |
|
Hard Disk Drive Space: |
30 MB |
As you can see, ApexSQL Doc requires MDAC 2.8 and the .Net 2.0 runtime. Both are not included in the software package, so you need to install them manually before installing the tool. If you don’t have both Pre-requisites already installed on your machine, you can get them from here
Within this 30 days trial period, the only thing reminding you of that trial is a start-up dialog:
After the 30 days trial period expires, the software stops working and you have to decide, how to proceed. In case, you decide to buy the software, check out the latest pricing information available on the ApexSQL homepage.
This is now the 3rd ApexSQL tool I know and just like the other two, ApexSQL Log and ApexSQL Clean, I haven’t experienced any difficulties getting familiar with the software. Its overall appearance has the same “Look and Feel” as the other aforementioned tools, and so you find yourself comfortable with the software after just a few hours of use. However, this time things are a little bit different….
Recall that the whole purpose of ApexSQL Doc is to “create” a documentation of one (or more) given SQL Server database(s). Keeping this in mind it isn’t really surprising to find that the software is actually “just” a wizard. A wizard that allows you to customize on 66 pages the level of granularity of your documentation down to the finest detail you require. You can virtually customize each and every single aspect of the documentation to fit your needs. As it is certainly beyond the scope of this paper, to show and describe each page for each possible setting separately, I deliberately choose instead several pages which, in my humble opinion, illustrate the usefulness of the tool pretty good and highlight some of its quite remarkable features.
But first things first, let’s have a look at the main application window
As you can see on the left-hand side, there is a Treeview object.
This Treeview not only illustrates that ApexSQL Doc is SQL Server 2005 ready, but also what I already mentioned above. You can customize almost every aspect of the database(s) that is to be documented down to the level that you require.
In order not to blow up this paper in size more than is necessary and to avoid this nasty horizontal scrolling when you have a screen resolution of just 1024×768, I will walk through the following explanations showing only in that part of the screen marked in red (or parts thereof) in the screenshot below. By the way, the user won’t ever lose control at which step in the documentation process he currently is, because the Treeview will be automatically adjusted and highlights that step.
As you can see, I’ve created several projects in which I’ve tried several different aspects of the software. Let’s open the documentation project on the database I use for all ApexSQL software papers.
Due to the sheer amount of possible screenshots, I won’t show you the typical SQL Server login screen and database selection screen. People familiar with SQL Server are familiar with such screens anyway. However, quite remarkable at the point of database selection, is the fact, that you can include more than one database from the same SQL Server instance to be included in just one documentation.
ApexSQL Doc allows you to include not only database objects in a documentation but also certain server level parts, such as the ones depicted below.
Next setting you can customize is the “Database Details” option. By enabling this option you can document certain database information such as owner, creation date, compatibility level, total size at time of documentation and database settings like “Auto Shrink” and others.
The Treeview Item with the most sub items by far is the “Object Types” item.
You probably have noticed the “Bitwise Set” textbox. It will change with every checkbox you activate or deactivate. The value shown in that box comes in handy when you want to use the Command Line Interface of ApexSQL Doc. I’ll have more to say about the Command Line in just a moment.
For database objects like Functions or Stored Procedures you can choose to document their options, parameters, permissions, and properties. For User-Defined Functions that return a table you can additionally choose to document what this table structure looks like.
Speaking of tables…
Most of the options shown are pretty much self-explaining. However, some of them require a little bit of explanation.