Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 
        
Home       Members    Calendar    Who's On


Add to briefcase ««123»»

Database Documentation: Joining up the Dots Expand / Collapse
Author
Message
Posted Monday, March 15, 2010 4:48 AM
UDP Broadcaster

UDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP Broadcaster

Group: General Forum Members
Last Login: Tuesday, November 18, 2014 2:50 AM
Points: 1,462, Visits: 3,029
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
Post #882793
Posted Monday, March 15, 2010 5:21 AM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Wednesday, September 12, 2012 8:44 PM
Points: 30, 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
Post #882805
Posted Monday, March 15, 2010 5:26 AM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Wednesday, September 12, 2012 8:44 PM
Points: 30, Visits: 145
Duplicate
Post #882808
Posted Monday, March 15, 2010 6:33 AM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: Thursday, October 9, 2014 8:58 AM
Points: 13, Visits: 107
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.
Post #882866
Posted Monday, March 15, 2010 6:35 AM


SSChampion

SSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampion

Group: General Forum Members
Last Login: Monday, November 17, 2014 12:50 PM
Points: 13,872, Visits: 9,598
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
Post #882867
Posted Monday, March 15, 2010 6:53 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: Administrators
Last Login: Today @ 10:17 AM
Points: 31,278, Visits: 15,731
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
Post #882885
Posted Monday, March 15, 2010 8:00 AM


SSChampion

SSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampion

Group: General Forum Members
Last Login: Monday, November 17, 2014 12:50 PM
Points: 13,872, Visits: 9,598
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
Post #882952
Posted Monday, March 15, 2010 8:33 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: Administrators
Last Login: Today @ 10:17 AM
Points: 31,278, Visits: 15,731
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
Post #882991
Posted Monday, March 15, 2010 9:26 AM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Wednesday, May 14, 2014 10:55 AM
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.
Post #883050
Posted Monday, March 15, 2010 2:43 PM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Friday, December 21, 2012 1:46 AM
Points: 28, 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.
Post #883351
« Prev Topic | Next Topic »

Add to briefcase ««123»»

Permissions Expand / Collapse