SQL Server Database Documentation is not done well.

Talking about documentation is rather like talking about doing your accounts, or tax return: Essential but not exciting. However, it illustrates so well the way that SSMS has drifted further and further from being the sort of tool that a database developer wants. It does not support documentation even for the minimum requirements of team working.

I’ve met many shades of opinion on what is required of database documentation, but the average developer wants, at least, to be able to inspect a list of routines, table, views or other routines in the database he is working on, together with a summary of what each one does, or what it represents. It would be nice to have the parameters listed as well, along with a phrase to explain each one. Anyone used to Visual Studio will want to be able to hover the mouse over a database object, column or index, and see a summary of what it is supposed to do.

Summary? What's that? The XML Documentation facility built into all the .NET languages allows you to put structured headers of well-formed XML into your code for all your classes. The three most important recommended tags are <param>, <summary>, and <remarks>.  Both <param> and <summary> are used by Intellisense, while all three are used by the VS ObjectBrowser. Where the compiler knows what should be in the tag, it will fill it in for you. As well as helping Intellisense, you can process this information to generate HTML, Word documents or printed reports via XSLT. You can feed the information into SandCastle to produce a help file, or compile it into a MAML help-authoring file.

SQL Server offers none of this. Mind you, I’m not happy with the idea of XML-based structured headers. I was brought up to work from a single gigantic database build script. Before extended properties in SQL Server, this was the only realistic way to get comments to apply to a table or column. Even now, things are little better. There is no consensus about the naming of extended properties; there is a lot of hand-crafting to be done before you can add structured headers to SQL routines, and even more to get the information out in an easy way, as reports and documentation. I currently use YAML fragments as structured headers. They are far easier than XML for us mortals to read and digest. However, I’m forced into a nightmare of coding to join up the dots sufficiently to generate all the required reports.

Team working with databases demands a much higher standard in documentation. Co-workers need the means to understand code as quickly as possible. Team leaders need to know who did what, when, and why. Managers need to be sure that quality standards are maintained and that progress is sure and predictable. Most important of all, the documentation for a production system has to allow people with a range of skills to understand, maintain and support the system.

At this point, I need to turn around and ask you, the reader, what you’d ideally like to get as the payoff for doing good SQL Server documentation. Intellisense? Help files? Intranet sites? MS Word reports? MAML? What, too, should be in those structured headers, and what is the ideal format for them?  Are there tools out there that will do it all? I’d love to know what you think.

Phil Factor.