SQL Clone
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


Database Documentation: Joining up the Dots


Database Documentation: Joining up the Dots

Author
Message
Carolyn Richardson
Carolyn Richardson
SSCrazy
SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)SSCrazy (2.9K reputation)

Group: General Forum Members
Points: 2925 Visits: 3538
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.

Facts are stubborn things, but statistics are more pliable - Mark Twain
Carolyn
SQLServerSpecialists
irozenberg
irozenberg
SSC-Enthusiastic
SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)

Group: General Forum Members
Points: 132 Visits: 145
In a real world, Carolyne you always challenged with a task to clean somebody else mess, and I was VERY VERY lucky
when I got couple of weeks to understand what exactly my team inherited in terms of data store
irozenberg
irozenberg
SSC-Enthusiastic
SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)SSC-Enthusiastic (132 reputation)

Group: General Forum Members
Points: 132 Visits: 145
Duplicate
NYProjectLeader
NYProjectLeader
SSC Journeyman
SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)SSC Journeyman (99 reputation)

Group: General Forum Members
Points: 99 Visits: 112
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.
GSquared
GSquared
SSC Guru
SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)

Group: General Forum Members
Points: 59007 Visits: 9730
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.

- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread

"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
Steve Jones
Steve Jones
SSC Guru
SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)

Group: Administrators
Points: 148985 Visits: 19446
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.

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
GSquared
GSquared
SSC Guru
SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)SSC Guru (59K reputation)

Group: General Forum Members
Points: 59007 Visits: 9730
Steve Jones - Editor (3/15/2010)
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.


I posted it on connect, https://connect.microsoft.com/SQLServer/feedback/details/541978/ddl-inline-documentation#

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.

- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread

"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
Steve Jones
Steve Jones
SSC Guru
SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)SSC Guru (148K reputation)

Group: Administrators
Points: 148985 Visits: 19446
Voted and added this comment

"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."

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
dmitra-1038570
dmitra-1038570
Forum Newbie
Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)

Group: General Forum Members
Points: 4 Visits: 23
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.
Ken Lee-263418
Ken Lee-263418
Valued Member
Valued Member (56 reputation)Valued Member (56 reputation)Valued Member (56 reputation)Valued Member (56 reputation)Valued Member (56 reputation)Valued Member (56 reputation)Valued Member (56 reputation)Valued Member (56 reputation)

Group: General Forum Members
Points: 56 Visits: 59
"...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.
Go


Permissions

You can't post new topics.
You can't post topic replies.
You can't post new polls.
You can't post replies to polls.
You can't edit your own topics.
You can't delete your own topics.
You can't edit other topics.
You can't delete other topics.
You can't edit your own posts.
You can't edit other posts.
You can't delete your own posts.
You can't delete other posts.
You can't post events.
You can't edit your own events.
You can't edit other events.
You can't delete your own events.
You can't delete other events.
You can't send private messages.
You can't send emails.
You can read topics.
You can't vote in polls.
You can't upload attachments.
You can download attachments.
You can't post HTML code.
You can't edit HTML code.
You can't post IFCode.
You can't post JavaScript.
You can post emoticons.
You can't post or upload images.

Select a forum

































































































































































SQLServerCentral


Search