SQLServerCentral / Editorials / SQLServerCentral.com / Database Documentation: Joining up the Dots / Latest Posts

RE: Database Documentation: Joining up the Dots

SSIS Guy — Mon, 02 May 2011 11:49:30 GMT

Here is one more [url=http://pragmaticworks.com/Products/Business-Intelligence/BIDocumenter/Overview.aspx]Free Tool to document Sql Server[/url]

RE: Database Documentation: Joining up the Dots

milzs — Mon, 22 Mar 2010 13:00:44 GMT

I would love to have the same XML documentation capabilities in SQL Server as in Visual Studio. I fact, we're using the same notation even though you can't do anything with it right now. It provides commonality between comments in our source code and database "code". Feeding this XML into Sandcastle for documentation is a tremendous asset, especially for projects with hundreds of classes and thousands of members.

RE: Database Documentation: Joining up the Dots

L' Eomot Inversé — Mon, 22 Mar 2010 05:42:57 GMT

[quote][b]GSquared (3/15/2010)[/b][hr]Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.[/quote]They acted with fairly great alacricity to close it as "won't fix". It was closed before I could vote for it.

RE: Database Documentation: Joining up the Dots

jezemine — Tue, 16 Mar 2010 10:11:58 GMT

I wrote a documentation tool called SqlSpec that supports SQL Server as well as 13 other platforms. It allows you to add an xml comment header to each proc/view/function etc just as people are discussing here. When you generate the docs, it will parse that header and create sections in the docs with that content, such as a change history, etc.Also there's an extended properties editor that allows you to easily add comments to all your objects. Of course those comments are fetched when the tool runs and put in the docs.link to it is in my sig. :-)

RE: Database Documentation: Joining up the Dots

GSquared — Tue, 16 Mar 2010 06:19:48 GMT

[quote][b]irozenberg (3/15/2010)[/b][hr][quote][b]GSquared (3/15/2010)[/b][hr][quote][b]Steve Jones - Editor (3/15/2010)[/b][hr]GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.[/quote]I posted it on connect, [url]https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#[/url]Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.[/quote]TO GSquared - Unfortunately you misunderstood my comments, I was referring to DDL triggers that means you could query system view and retrieve SP/UDF parameters meta data AFTER data object had been modified. Parameters definition could be easily assembled into XML document and updated under key "Parameters" under SP/UDF Extended Properties.[/quote]I wasn't responding to your comment. Steve replied to me, and I replied to him. What you're suggesting is what I said could be an alternative to the idea of a specific parameter for the DDL create/alter commands.

RE: Database Documentation: Joining up the Dots

irozenberg — Mon, 15 Mar 2010 18:53:26 GMT

[quote][b]GSquared (3/15/2010)[/b][hr][quote][b]Steve Jones - Editor (3/15/2010)[/b][hr]GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.[/quote]I posted it on connect, [url]https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#[/url]Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.[/quote]TO GSquared - Unfortunately you misunderstood my comments, I was referring to DDL triggers that means you could query system view and retrieve SP/UDF parameters meta data AFTER data object had been modified. Parameters definition could be easily assembled into XML document and updated under key "Parameters" under SP/UDF Extended Properties.

RE: Database Documentation: Joining up the Dots

Ken Lee-263418 — Mon, 15 Mar 2010 16:34:16 GMT

Thanks for the documentation. I supposedly have version 3.5. I haven't figured out how and where to put /doc:filename in Visual Studio. It appears to be a command line option. One of the first things I tried was ''', also '', then just '. Nothing produces the XML framework automatically generated by /// in C#.If I have to write a separate XML file to store my documentation, it just isn't worth the work. Neither is manually writing in all the ''' XML formatting inline above each object/routine, especially if my VS won't recognize it. (My Intellisense DEFINITELY does NOT recognize it using the ''' like /// in C# and XML formatting like C#.)MY VB help specifically states XML documentation is NOT supported in VB.NET.Whatever version I've got, it sucks.This version will not compile C# in VS (Developer's version bought specifically for VB.NET.), but it does support XML documentation in C#.

RE: Database Documentation: Joining up the Dots

Phil Factor — Mon, 15 Mar 2010 15:32:09 GMT

[quote]The XML Documentation facility built into all the .NET languages..." - I wish! VB.NET supports intellisense so the hovering images of what something does will be supported if you are looking at something generated in another language. I tried all I could think of to start that facility until I read specifically that it isn't supported in VB.NET[/quote]For details of C# XML Documentation see[b] [url=http://msdn.microsoft.com/en-us/library/b2s063f7%28VS.100%29.aspx]XML Documentation Comments (C# Programming Guide)[/url].[/b] For the same in F# see [b][url=http://msdn.microsoft.com/en-us/library/dd233217%28VS.100%29.aspx]XML Documentation (F#)[/url][/b]. The latter reference contains the quote [quote]The support in F# for generating documentation from comments is the same as that in other .NET Framework languages. As in other .NET Framework languages, the -doc compiler option enables you to produce an XML file that contains information that you can convert into documentation by using a tool such as Sandcastle[/quote]. You can most certainly use XML Documentation in VB.NET. See [b][url=http://msdn.microsoft.com/en-us/library/f64ezf9b.aspx]Documenting Your Code with XML (Visual Basic)[/url][/b] The compiler switch is the same, and there are several links in the URLs I've given that will explain the system in detail. There is even XML documentation support in IronPython. I hope that is useful.

RE: Database Documentation: Joining up the Dots

Ken Lee-263418 — Mon, 15 Mar 2010 14:43:37 GMT

"...The XML Documentation facility built into all the .NET languages..." - I wish! VB.NET supports intellisense so the hovering images of what something does will be supported if you are looking at something generated in another language. I tried all I could think of to start that facility until I read specifically that it isn't supported in VB.NET.Yes, it would be nice if that facility was built into SQL as well, however the intellisense currently built into SQL 2008 is 1 out of 10 times helpful and 9 out of 10 clueless, distracting, and throws me off. It's like a 3 year old with no clue of what you are doing trying to be helpful. In other languages, you type "Me." or "this." to tell the system, yes, I expect some help.That "mind reading" comment made elsewhere belongs with the Microsoft supplied intellisense, which is very apt. And yes, it isn't a full-blown documentation tool, but at least you can get a 1 line reminder of what something is for, at least in your own coding practices.

RE: Database Documentation: Joining up the Dots

dmitra-1038570 — Mon, 15 Mar 2010 09:26:37 GMT

SQL script files are free format text files.If we turn that into a structured format, e.g. XML, users will strart filling up various tags to document along with the coding process.There can be various XML templates made avaible for the developers to use the structure to code for various types of SQL objects.

RE: Database Documentation: Joining up the Dots

Steve Jones - SSC Editor — Mon, 15 Mar 2010 08:33:16 GMT

Voted and added this comment [i]"I like the idea of somehow adding details about a change. This would be great for an audit log. If there were a parameter per column, or even per item, this could be stored in extended properties as well, allowing for more detailed documentation about an object."[/i]

RE: Database Documentation: Joining up the Dots

GSquared — Mon, 15 Mar 2010 08:00:08 GMT

[quote][b]Steve Jones - Editor (3/15/2010)[/b][hr]GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.[/quote]I posted it on connect, [url]https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#[/url]Since it's a minor need and non-trivial change to how the T-SQL engine would parse out DDL commands, I wouldn't expect Microsoft to act on it with any alacrity. But I posted it anyway. Feel free to comment/vote on it, of course.

RE: Database Documentation: Joining up the Dots

Steve Jones - SSC Editor — Mon, 15 Mar 2010 06:53:18 GMT

GSquared, I like the idea of the parameter. That would be very handy to know during the creation of modification of some DDL statement. That could then be exposed later in documentation or when someone has a question about a field.

RE: Database Documentation: Joining up the Dots

GSquared — Mon, 15 Mar 2010 06:35:09 GMT

I think it would be useful to have a Comments "parameter" for the various create and alter DDL commands. If it could handle XML, that would be great. The data thus created should be accessible through sys.all_objects, sys.tables, et al. If the XML scheme for this had a default, but could be replaced/modified/enhanced as required, that would be even better.Beyond that, trapping DDL commands and logging them via a trigger, then having an XML Comments column in the logging table, is a viable but much less valuable alternative. Much too prone to "I forgot to update it". Could set up a job to run at the end of the night and send an e-mail to the DBA and the dev if something in the log still doesn't have a comment by then.I haven't implemented such a system, but it would probably work.

RE: Database Documentation: Joining up the Dots

NYSystemsAnalyst — Mon, 15 Mar 2010 06:33:28 GMT

I try to do at least some basic documentation for my DBs. I put a description on all non-intuitive fields, and I use structured headers for all stored procedures and functions (including summary, author, date created, change history, etc.). It would be nice to have this information available in a popup when hovering and it would be nice to have that info automatically included in documentation output. For example, we use the SQLDOC tool from RedGate. It a nice utility and it includes the field descriptions in the documentation output, but it would be nice to have the stored procedure / function summaries and parameters descriptions included as well. Having a documentation tool built in to the software instead of having to buy a third party tool would be nice as well.

RE: Database Documentation: Joining up the Dots

irozenberg — Mon, 15 Mar 2010 05:26:31 GMT

Duplicate

RE: Database Documentation: Joining up the Dots

irozenberg — Mon, 15 Mar 2010 05:21:40 GMT

In a real world, Carolyne you always challenged with a task to clean somebody else mess, and I was VERY VERY luckywhen I got couple of weeks to understand what exactly my team inherited in terms of data store

RE: Database Documentation: Joining up the Dots

Carolyn Richardson — Mon, 15 Mar 2010 04:48:01 GMT

In an ideal world (still looking for it) you would design all your databases from a model, using a good tool, my preference Power Designer (Sybase). Then apply all changes to the model first, so you would always have an accurate model of your database and you could always see what would be impacted when changing your database. The model would end up generating the documentation and data dictionary.Unfortunately it never seems to work that way anymore, business want change to happen far to quickly, so they just rush into the development not taking the time and effort to put down the ground work in the design stage. They always end up paying the price later, but then that comes out of a different budget.

RE: Database Documentation: Joining up the Dots

RunnerIE — Mon, 15 Mar 2010 04:20:15 GMT

Has anyone documented a database that was for a Medical Device / Phara environment application and how did you achieve it? Tks.

RE: Database Documentation: Joining up the Dots

irozenberg — Sun, 14 Mar 2010 17:17:37 GMT

You could use DDL Trigger - every time when SP/UDF had been modified, it will retrieves list of input/output parameters, build an XML document and store it with designated key in Extended Properties. BTW you even could snap and record definition of recordset(s) returned by SP/UDF (with SQL CLR code).

RE: Database Documentation: Joining up the Dots

Steve Jones - SSC Editor — Sun, 14 Mar 2010 11:06:23 GMT

I've usually only documented databases at a point in time, when there is this need to a large scale change to the system, or a lot of new developers start working with things. Otherwise is seems that we almost require someone to build their own knowledge as they go along as a way of understanding the system.If there was some other benefit, and we could easily access documentation, I think it might be more valuable. Especially if we could easily expose things like Extended Properties in places like SSRS where a user could better understand what they are working with. It would be great if a view read back through to the EP of the source table as well and exposed the data there.

RE: Database Documentation: Joining up the Dots

emanovs — Sun, 14 Mar 2010 07:41:14 GMT

I'm using extended properties. Just by filling them in the SSMS Database Diagram but it's obviosly pretty inconvenient cause it does not cover documentation of SPs/FNs etc.

RE: Database Documentation: Joining up the Dots

alakritz — Sun, 14 Mar 2010 04:28:29 GMT

Nice tool - thanks for the tip!

RE: Database Documentation: Joining up the Dots

Mark Stacey — Sat, 13 Mar 2010 23:26:40 GMT

I use the tool BIDocumenter, from Pragmatic Works (http://www.pragmaticworks.com) Disclaimer : we signed up as a reseller locally.But the reason we did is that it is an excellent tool, documenting the DB, SSIS packages, SSAS cubes, and SSRS And also has data lineage - showing where data came from

RE: Database Documentation: Joining up the Dots

irozenberg — Sat, 13 Mar 2010 20:52:59 GMT

I am using Extended properties for ages. But I agree with Phil - vendor should provide better Documenting facilities, rather than force us to "re-invent the wheel" in DIY solutions!

RE: Database Documentation: Joining up the Dots

dg81328 — Sat, 13 Mar 2010 18:25:25 GMT

Phil,In my mere 15 years I rarely if ever receive a request to document a database. That covers hundreds of them over hundreds of projects. In my programming days it was "get it done asap". As an admin it's "fix it asap". As a lead it's "fix it asap and who do I blame?"Modern documentation in my experience is the purvue of the Indian outsourcers looking for a way to duplicate our work in cookie-cutter fashion. And their documentation never reflects what really goes on.It's entirely possible, even likely, that I have no idea what you are talking about. If that's the case, it doesn't say much for the documentation quality of your editorial.That leads to my main point. Documentation explains simply and clearly what an object, function or property does. It provides working examples. Intellisense is not documentation. It is Microsoft's attempt at reading minds.

RE: Database Documentation: Joining up the Dots

alakritz — Sat, 13 Mar 2010 14:07:53 GMT

I have been documenting our database platform for nearly 9 years. We use structured headers for stored procedures and views (including summary, parameters, blocks, remarks and about a dozen others), and my tool Document X! parses those objects and creates an HTML documentation project. I then import that into a RoboHelp 8 project and create a searchable, indexed Web Help project that I publish on the company intranet. Document X! does a great job pulling out the logical relationships in the databases, including all dependencies (in both directions), and the scripts and schemas. I get the stored procedures, views, tables, and any other object I might want to include in the technical documentation (defaults, user defined functions, user defined data types, full text catalogs). I can even get permissions if necessary. The value of publishing it as a RoboHelp Web site is that all of the objects are fully searchable so that you can find things fast. The other value: the entire software development and database administration team has a structure and methodology to hang their documentation on so that standards prevail within the team as a whole. In the early years of the project, I spent a lot time in the code itself writing comments. In the last few years, only developers write the comments to their code. Document X! even picks up the version comments generated automatically by the team's version control tool, so that the name of the developer, the date, the version, and a version comment is captured and published to the documentation web site. One place for all comments. I have the option as well to publish the full text of the stored procedures, or just the comments and headers. My site includes everything.

Database Documentation: Joining up the Dots

Phil Factor — Fri, 12 Mar 2010 11:37:23 GMT

Comments posted to this topic are about the item [B]Database Documentation: Joining up the Dots[/B]