May 17, 2002 at 12:49 am
Hi,
at my current assignment they do not document the databases.
So I am about to recommend that practise.
So I wonder, how does everybody else do?
Do you document your databases?
Do you document your stored procedures?
Do you document your triggers?
Do you know of a suitable repository / data dictionary?
For those using ERwin, PowerDesigner, ERstudio etc, do you document in or
outside those tools?
How do you publish the documentation?
I would be very thankful for any response.
(posted this at microsoft.public.sqlserver.programming but got no particular response except from Tibor)
May 17, 2002 at 5:11 am
1) FOr the most part no, at least not like we should here. I comment my code and make script copied of the DBs but not all the developers here do the same. Some do make true documentation but our inhouse developement is too heavy to spend a lot of time on any one project.
2) Same as above except the SP geta nice header for documentation to explain what they do. Liek this
/*
*Pocedure Name:ip_GetDetailEquip
*Full Name:Get Equipment detail based on Employee ID
*Created:6/8/2001
*Created By:James Travis
*Last Modified:
*Modified By:
*
*Desc: This procedure is designed to look up base detail of Equipment from inventory.
*
*/
3) Same as SPs
4) No.
5) Don't use any of these.
6) We don't which is a major pain when omeone leaves trying to find out what is going on, comments in code have been our best friend (even in cases where there is a nice set of documentation).
However everything we don't do you should do (except cannot give you a good answer on 4 and 5 as you can build an access db taht is better than anything, depends on what you need and how comfortable you are).
"Don't roll your eyes at me. I will tape them in place." (Teacher on Boston Public)
May 21, 2002 at 6:33 pm
If I can have it my way, I would at least do the following:
1) Create a Word document that describes the main conceptual/logical entities with simple VISIO Diagrams
2) Always fill in the Table/column definitions in ERStudio logical design diagram.
3)Add a paragraph that describes the set of database objects to be created before the actual scripts.
Then store these three documents in a directory called "release x". When someone makes a change, all three documents should be updated, and the old version goes to archive.
I have also been in a company(Insurance) that requires every program/script to be accompanied with a design document, which then be cut and pasted on the script as comments. These design documents are compiled into HTML and published on the Intranet. Each subsequent changes are dated/signed/appended at the end of the remarks.
BUT, it is not realistic to expect this out of every project/every company/every team. There are just all sorts of resistance to it. Currently, I am working in an environment where people simply won't document anything. But they really should.
May 22, 2002 at 5:24 am
I think you have to assess the real value of a document. One of the things I've picked up from XP/Agile Modeling is that documentation has a cost, you can either document or code, which would the customer prefer? That's not to say documenting at all is bad, but it should serve a real purpose. The only documentation I currently require is that all procs/functions have a line in the header containing revision date, who did it, a one sentence line about why the change was made.
Other than that, there's not much I can't get from EM. I will say that I find diagrams VERY valuable. Problem is in a lot of cases there will be no foreign key constraints to help the generation of a diagram automatically. Having something you can stick on the wall while you work is a lot better than alt tabbing back and forth.
Andy
May 22, 2002 at 5:53 am
<quote Tibor Karaszi, SQL Server MVP>
I just like to share a method that work fine for a small project that I'm involved with now. We are documenting the tables,
where the definition is stored with the tables themselves. Using the Extended Properties
functionality. So far, I've documented all tables and columns, using only the MSDescription tag.
But you can have as many tags as possible for an object/column (like written by, creation date,
last modified, input mask etc).
Only down side so far is lack of support for this in tools. I'm doing all with TSQL.
But it would really be dead easy to write a small app with an easy to use UI for this. Shouldn't take more than a few hours. I
haven't had the need for it yet, quite simply (I'm importing all the DDL into a VB program that
will to the install and upgrade of tables, so I need the proc's in the end anyhow). All I've
done so far is a proc which lists all MSDescription properties on a table and it's columns.
FWIW, extended properties can be defined on constraints as well...
</quote>
Anybody care to write some sp:s.....
Viewing 5 posts - 1 through 4 (of 4 total)
You must be logged in to reply to this topic. Login to reply