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
Phil Factor
Phil Factor
SSCrazy
SSCrazy (2K reputation)SSCrazy (2K reputation)SSCrazy (2K reputation)SSCrazy (2K reputation)SSCrazy (2K reputation)SSCrazy (2K reputation)SSCrazy (2K reputation)SSCrazy (2K reputation)

Group: General Forum Members
Points: 2008 Visits: 2971
Comments posted to this topic are about the item Database Documentation: Joining up the Dots


Best wishes,

Phil Factor
Simple Talk
alakritz
alakritz
Valued Member
Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)

Group: General Forum Members
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.



dg81328
dg81328
SSC Rookie
SSC Rookie (29 reputation)SSC Rookie (29 reputation)SSC Rookie (29 reputation)SSC Rookie (29 reputation)SSC Rookie (29 reputation)SSC Rookie (29 reputation)SSC Rookie (29 reputation)SSC Rookie (29 reputation)

Group: General Forum Members
Points: 29 Visits: 160
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.
irozenberg
irozenberg
Valued Member
Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)

Group: General Forum Members
Points: 66 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!
Mark Stacey
Mark Stacey
Valued Member
Valued Member (64 reputation)Valued Member (64 reputation)Valued Member (64 reputation)Valued Member (64 reputation)Valued Member (64 reputation)Valued Member (64 reputation)Valued Member (64 reputation)Valued Member (64 reputation)

Group: General Forum Members
Points: 64 Visits: 160
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
alakritz
alakritz
Valued Member
Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)Valued Member (68 reputation)

Group: General Forum Members
Points: 68 Visits: 12
Nice tool - thanks for the tip!



emanovs
emanovs
Forum Newbie
Forum Newbie (2 reputation)Forum Newbie (2 reputation)Forum Newbie (2 reputation)Forum Newbie (2 reputation)Forum Newbie (2 reputation)Forum Newbie (2 reputation)Forum Newbie (2 reputation)Forum Newbie (2 reputation)

Group: General Forum Members
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.
Steve Jones
Steve Jones
SSC Guru
SSC Guru (62K reputation)SSC Guru (62K reputation)SSC Guru (62K reputation)SSC Guru (62K reputation)SSC Guru (62K reputation)SSC Guru (62K reputation)SSC Guru (62K reputation)SSC Guru (62K reputation)

Group: Administrators
Points: 62266 Visits: 19102
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
My Blog: www.voiceofthedba.com
irozenberg
irozenberg
Valued Member
Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)Valued Member (66 reputation)

Group: General Forum Members
Points: 66 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).
RunnerIE
RunnerIE
SSC Rookie
SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)SSC Rookie (47 reputation)

Group: General Forum Members
Points: 47 Visits: 3192
Has anyone documented a database that was for a Medical Device / Phara environment application and how did you achieve it? Tks.
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