Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

SQL Server tool alleviates documentation headaches

Many database pros dread the hassle of SQL documentation. Fortunately, the right tool can speed up and simplify the process considerably.

I don’t think I’ve met a single person who likes generating documentation for code. This is the same for database programmers who tend to avoid documenting either code or structures in their creations, much to the chagrin of whoever ends up inheriting their work. It’s a tough habit to get into, as many developers find it just as easy to keep all the notes in their heads.

Consequently, I’ve been growing more curious about SQL Server documentation tools that allow database administrators to document their creations—not just for themselves but for others, since even a well-designed data structure might not be as intuitive to the rest of the world. To that end, I took a closer look at Red Gate Software’s SQL Doc, one of many tools designed for SQL Server developers and administrators.

SQL Doc is a simple yet effective documentation tool. It connects to an existing database (you supply the server name and credentials) and lets you browse the list of objects therein and add details to be stored in the Description column for that object. SQL Doc works closely with SQL Server’s own native structures for providing documentation and makes it a lot easier to add description data compared to SQL Server Management Studio (SSMS). Moreover, because the program is much smaller than SSMS, it’s also much faster.

There are many useful attributes at your fingertips with SQL Doc, and almost every element of the database schema can be annotated. For instance, click on an object in the tree and you’ll see a list of its major properties, its columns or parameters, the raw SQL script used to generate the object and the uses/used by information for that object. Click Edit for any item description and an edit window will pop up where you can type a description for that attribute. There are also Previous and Next options in the edit window that let you move between attributes without having to close and reopen the window. This is handy when you’re dealing with an object that has many attributes.

SQL Doc can also take these attributes and produce offline documentation with them, which is at least half of the real utility of this program. For example, the Generate Documentation option provides a prompt to create a .doc file, help file or collection of webpages. The compiled documentation is very close to what you see in the program itself when you’re exploring database objects; it not only includes the comments you’ve edited, but the scripted versions of the objects as well.

From what I’ve seen so far, SQL Doc serves as a way to begin producing the documentation you need for a database. I wouldn’t yet go so far as to call it a total solution, but it’s a good start and from that base you can build quite a bit. In terms of pricing, the program is available as a 14-day trial and costs $295 for a single-user license, with steep discounts for bulk purchases.

Figure 1. SQL Doc’s edit window (click to enlarge)
 SQL Doc’s edit window lets you move quickly between multiple attributes in the same database object

Serdar Yegulalp has been writing about computers and information technology for more than 15 years for a variety of publications, including InformationWeek and Windows Magazine.

Dig Deeper on Microsoft SQL Server Tools and Utilities

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.