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 Friday, March 12, 2010 11:37 AM


Mr or Mrs. 500

Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500

Group: General Forum Members
Last Login: Today @ 7:18 AM
Points: 587, Visits: 2,552
Comments posted to this topic are about the item Database Documentation: Joining up the Dots


Best wishes,

Phil Factor
Simple Talk
Post #882003
Posted Saturday, March 13, 2010 2:07 PM
Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Thursday, March 25, 2010 1:50 PM
Points: 68, Visits: 12
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.


Post #882420
Posted Saturday, March 13, 2010 6:25 PM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Wednesday, January 22, 2014 7:47 AM
Points: 9, Visits: 151
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.
Post #882440
Posted Saturday, March 13, 2010 8:52 PM
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
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!
Post #882468
Posted Saturday, March 13, 2010 11:26 PM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Sunday, October 19, 2014 2:04 PM
Points: 44, Visits: 158
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
Post #882499
Posted Sunday, March 14, 2010 4:28 AM
Valued Member

Valued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued MemberValued Member

Group: General Forum Members
Last Login: Thursday, March 25, 2010 1:50 PM
Points: 68, Visits: 12
Nice tool - thanks for the tip!


Post #882550
Posted Sunday, March 14, 2010 7:41 AM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Saturday, September 20, 2014 4:24 PM
Points: 2, Visits: 39
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.
Post #882568
Posted Sunday, March 14, 2010 11:06 AM


SSC-Dedicated

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

Group: Administrators
Last Login: Today @ 12:34 PM
Points: 31,181, Visits: 15,626
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.







Follow me on Twitter: @way0utwest

Forum Etiquette: How to post data/code on a forum to get the best help
Post #882592
Posted Sunday, March 14, 2010 5:17 PM
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
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).
Post #882639
Posted Monday, March 15, 2010 4:20 AM
Grasshopper

GrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopperGrasshopper

Group: General Forum Members
Last Login: Wednesday, September 3, 2014 7:58 AM
Points: 13, Visits: 3,162
Has anyone documented a database that was for a Medical Device / Phara environment application and how did you achieve it? Tks.
Post #882780
« Prev Topic | Next Topic »

Add to briefcase 123»»»

Permissions Expand / Collapse