Is this 'Documentation'? 2

[Gooser]

I was recently given the following as 'documentation' of a database project. In my very humble opinion this is complete garbage. This is no more than a SELECT from the table with EntityName and EntityShortDescription, I got it as an XLS. The other problem I have with this is that the descriptions are short and really only re-word the entity names. Am I wrong to raise the BS flag on this? Would this be acceptable 'documentation' in your shop? I would love to hear your opinions on this.

[b]
Entity Name                    Short Description
------------------------------ -----------------------------
[/b]
AccessMechanism                An entity that stores
                               information about the means
                               to contact a party.
ActualProjectedWall            An entity that stores
                               information about an existing
                               wall projected in a single
                               map direction (i.e. North
                               South)
ActualProjectedWallComposition An entity that stores
                               information about the wall
                               composition of a
                               ActualProjectedWall.
AdministrativeChangeEvent      An entity that stores
                               information about a
                               Administrative Change type
                               of VersionEvent.
ASAlarmMonitoringServiceRole   An entity that stores
                               information about a
                               ASAlarmMonitoringServiceRole
                               type of OccupantRiskRole
                               RiskRole.
ASDesignSystemSectionPart      An entity and table that
                               stores information about a
                               AS Design System (AS System)
                               installed in a Risk
                               Component Section Part.

...

<many more lines follow--truncated for brevity>

Thank you for your time.


v/r

Gooser

Why do today
that which may not need to be done tomorrow --me

 

[AlexCuse]

My boss would ask me to write a ten-page word document on each 'entity name'.

But seriously, no that would not cut it. Where are relationships, table names, data types, views needed, etc........

What you have is not even close, I would raise the BS Flag. Better that than develop the whole thing and come back to hear 'oh, that's not what I wanted'.

Alex

Professor: But what about your superintelligence?
Gunther: When I had that there was too much pressure to use it. All I want out of life is to be a monkey of moderate intelligence who wears a suit. That's why I've decided to transfer to Business School.
Professor: NOOOOOOOOOOOO.

 

[r937]

looks to me like the typical deliverable from someone who was told to produce documentation

blame the manager and/or the methodology!! ;-)

no, it isn't BS but the signal to noise ratio is awfully low

r937.com | rudy.ca

 

[Gooser]

A little more info on this. This is 'documentation' for the database that they (the contractor our company hired) already built, (by 'built' of course, I mean schlubbed together with paperclips, dynamic SQL and chewing gum.) They've been on this project since sometime around the middle of 2004 and have bled the company to the tune of hundreds of thousands of dollars. I was hired around the middle of this year and I've been asking for documentation of requirements since shortly after my hire-date. Just two days ago, I get a link to a shared drive that has a hundred(? or so) emails on it with attached 'documentation'. Some are 'meeting notes' (not minutes, but random, un-developed thoughts about what was said at meetings a year/two-years ago), many are similar to what I posted above, some are much worse--if you can believe that. What I posted above, is where I was told to start looking at the 'documentation'.

It's like this contractor's CMM level is [small]NEGATIVE[/small] 3!

[frustrated]
--Gooser

 

[AlexCuse]

Ah, it is suddenly much more clear. I thought you were going to need to build a db from those specs.

Sounds like a contractor who threw together documentation as an afterthought, and perhaps even hoped if it was unclear he would stick around a while?

It looks like something that if you were sitting looking at the database you could figure it out, but means next to nothing (what the he11 is an entity referring to on some of those) if you can't poke around while reading? 'An entity and table' is very clear though ;-)

Good Luck Gooser!

Alex

Professor: But what about your superintelligence?
Gunther: When I had that there was too much pressure to use it. All I want out of life is to be a monkey of moderate intelligence who wears a suit. That's why I've decided to transfer to Business School.
Professor: NOOOOOOOOOOOO.

 

[Gooser]

Alex - Thanks for the support. The sad thing is, I probably will have to create a database, because what they've developed thus far is IMHO unmaintainable. [hyperbole]It is the shoddiest piece of database construction ever, in the entire universe![/hyperbole]

There is a complete lack of useful documentation.

Every good-practice is blatantly shrugged.

The database isn't normal, not even a little normal.

If I had some kind of documentation of requirements, I could create my own System Requirements Specification, and start from there, but every time I ask for documentation, I am bombarded with piles of crap 'documentation' instead.

--Gooser

 

[SQLSister]

My suggestion to you is that you specify what you need from them very specifically. Make up a blank format for the documentation you need to maintain the system and have them fill it in and return it. Keep sending it back until they get it right. Depending on how the contract is written, they may or may not be required to fdo this without being paid more, check with your contacting types to see before you present this to your boss.

Questions about posting. See faq183-874

 

[Catadmin]

Ditto to SQLSister's comment. And find out if they have Erwin or another data modeling tool. If they do, make them diagram the database for you as well as filling out the documentation.

Database diagrams are, IMHO, a life-saving kind of tool. Especially when paired with a set of well-written Business Rules (don't let them forget these) and database documentation.


Catadmin - MCDBA, MCSA
"No, no. Yes. No, I tried that. Yes, both ways. No, I don't know. No again. Are there any more questions?"
-- Xena, "Been There, Done That"

 

[Gooser]

Catadmin - ERWin was one of the first things I asked for upon my hire here. Immediately after getting a copy, I reverse-engineered the database and was [small]ASTOUNDED[/small] at what I found. The structure is unlike any other I have ever seen. Rather than one 'lookup' table for each time one is needed, there is one GIANT lookup table that all of the tables relate back to. This table holds metadata for each of the 'attribute types'. It is kind of hard to explain, especially since it doesn't follow any of the rules of good database design.

Given this model:

attr_value_list_item
??????????????????????????????????????
?                                    ?
??????????????????????????????????????
? attr_value_list_item_id            ?
? attr_value_list_item_type_value_id ?
? attr_value_list_nm_id              ?
? item_cd                            ?
? nm                                 ?
? short_descr                        ?
? descr                              ?
? ...                                ?
??????????????????????????????????????
                 ?
                 ?
blah             ?
?????????????????????????????????????
? blah_id                           ?
? blah_value                        ?
?????????????????????????????????????

attr_value_list_item is a real table, blah, of course, is not. There are over a hundred of blah-like tables throughout the database, and each one relates back to attr_value_list_item via non-identifying relationships. Everything is varchar(512) and there aren't any primary keys on the tables. The attr_value_list_item has 60-something-thousand rows and ranges of those rows are what should be in separate lookup tables. Of course, if you add something to a lookup set it goes to the end of the attr_value_list_item table and is therefore, nowhere near its 'home range'.

This doesn't make any sense (to me), and flies in the face of everything I know about RDBMSs. The only thing that seems to be getting engineered here is more billable hours for our contractor.

RRRGH!

--Gooser

 

[r937]

no explanation required

search the web for "one true lookup table" and see what others have written about it

also, i think you are absolutely correct about the billable hours

;-)

r937.com | rudy.ca

 

[Catadmin]

Are you sure they aren't trying to design a data-warehouse solution instead of a database solution? Because one giant lookup table sounds like something an analysis services person would do.

Of course, never having designed a DW solution, I don't know for sure...


Catadmin - MCDBA, MCSA
"No, no. Yes. No, I tried that. Yes, both ways. No, I don't know. No again. Are there any more questions?"
-- Xena, "Been There, Done That"

 

[Gooser]

r937 - by 'search the web', do you mean Google?

[/feigned confusion]

--Gooser

 

[djj55]

One giant lookup table is what we used MANY years ago (started by an outside contractor). Maybe you have a dinasor programmer stuck in a tar pit.
djj

 

[Gooser]

r937 - if I could give you two stars for one post, I would. Finally black and white justification for what I've been saying all along. The phrase "one true lookup table" is [small]EXACTLY[/small] what I needed.

Thank you so much!

--Gooser

 

[r937]

thanks

i prefer "search the web" because it's inclusive

nothing against google, i'm a very satified googler myself, it's just that sometimes the other search engines have good stuff too

;-)

r937.com | rudy.ca

 

[Catadmin]

Yuck, yuck, yuck!!!!

I just looked up the term myself. Now I'm going to have nightmares for weeks! @=)

You know, we actually have one business analyst who keeps advocating using a generic lookup table, but since the developers & DBAs ignore him (he just gives the recommendation, we get to choose the schema), I never thought anything of it. Now I know what to tell him next time.

Thanks, R937.


Catadmin - MCDBA, MCSA
"No, no. Yes. No, I tried that. Yes, both ways. No, I don't know. No again. Are there any more questions?"
-- Xena, "Been There, Done That"

 

[r937]

i dug up my links on this topic --

One True Lookup Table

http://www.dbazine.com/ofinterest/oi-articles/celko22

by Joe Celko

OTLT and EAV: the two big design mistakes all beginners make

http://tonyandrews.blogspot.com/2004/10/otlt-and-eav-two-big-design-mistakes.html

Lookup Table Madness

http://www.sqlservercentral.com/columnists/dpeterson/lookuptablemadness.asp

(also called Massively Unified Code-Key tables, or MUCK tables)


r937.com | rudy.ca

 

[AlexCuse]

Wow. That should be enough to frighten me all the way through halloween. Thanks for saving me the $5 it would've cost to rent 'Halloween', r937

Professor: But what about your superintelligence?
Gunther: When I had that there was too much pressure to use it. All I want out of life is to be a monkey of moderate intelligence who wears a suit. That's why I've decided to transfer to Business School.
Professor: NOOOOOOOOOOOO.

 

[Gooser]

Every time I think of the work it'll be for me to maintain this thing when it's working, it literally makes me want to vomit.

--Gooser

 

[AlexCuse]

Hang in there, buddy!

A wise man once said
"The only thing normal about database guys are their tables".