AUTOMATE Documentation Generation

No one likes generating documentation from T-SQL procedure and function comments. Today as part of T-SQL Tuesday #110, we look at how we can use XML comments for our objects and use T-SQL to automatically generate documentation from them.

Related blog post with query examples:

Follow me on Twitter:

[sql]

Bert, What a great idea. Would love to see an a more in depth example in another one of your videos. Keep this great information coming. Thoroughly enjoy the topics each week.

[zanonilabuschagne]

Thanks Bert!! We've got a tool for documentation; it's called the intern :-)

Jokes aside, one of the easiest SQL features for documentation of data that we use for DDL, is the "Description" column when creating tables in Visual Studio (or using extended properties in TSQL). Yes, it is a pain upfront, but then, you have the Business definition of a field right there with your data types, making your data dictionary an absolute breeze to generate.

We use to use DGML in Visual Studio for our process flows, but the technology never really caught on, which is a pity; the file is stored in XML, which means you could then store the graphical flows in the same way you mentioned in your video. If MS (specifically SQL) had more DGML support, it could have been amazing, but the overhead involved in updating it on a change request was just too cumbersome. So, now Visio it is, and we just put hyperlink to the files in our proc and application code. Not ideal, but what's the alternative :)

In a future video, it would be great if you can get the MS view & tooling of the whole SDLC - Using one tool, can you get BA's to document their analysis, which then becomes storyboards, process flows, architecture docs and then code. Once Code, generate test cases, final UAT docs, then implementation models. Everything does exist in "pieces" in Visual Studio but seeing the "whole thing" will be awesome!!

Thanks for this weeks vid, from a warm, sunny South Africa :)

[yonihbc]

can you share the code for reading trough all the SP xml notes?

[pawjershauge]

Hey Bert, thanks for your great work, love to see your videos. Regarding the XML documentation. How come you don't use extended properties instead, they also live and die with the object. And they are truly there for this purpose. You can event make example properties and lots of other stuff.
I have as set of ep's that I always include, like; who's the developer, whats the version of the object, examples of usage, what does it do and so on.. its great for doing exactly that and its just there besides the code/object.
Any reason not to do that ???