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

 

[Catadmin]

Gooser,

The below article is from the contractor's POV instead of the client's, but it should provide you with some information on what questions you should be asking about this contract. Hope it helps.

http://www.simple-talk.com/opinion/opinion-pieces/contract-coding-ensuring-your-client-pays-up/

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"

 

[SQLDenis]

>>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.

That's why I don't write documentation but have a web site. The 'documentation' is always current because I use the INFORMATION>SCHEMA ANSI views to return all the details

here is an example I have a page with all the tables (populated from a DB of course, not hardcoded)
The user clicks on the table then a proc is called

CREATE procedure dbo.SchemaTable 
@chvTableName varchar(255)
as
set nocount on
select column_name,data_type,coalesce(column_default,'') as column_default,is_nullable,
CHARACTER_MAXIMUM_LENGTH,
NUMERIC_PRECISION, 
NUMERIC_PRECISION_RADIX ,
NUMERIC_SCALE
 from INFORMATION_SCHEMA.COLUMNS 
where table_name = @chvTableName
order by ordinal_position
set nocount off

which return some info about the table. I have procs like this for procs/function, constraints, keys
The tables details page will pull table, key and constraint info

This 'doc' is always up to date because the info is pulled straight from the DB

You can also add extended properties of course that describe the columns etc. But you still have to maintain that at the DB level



Denis The SQL Menace
SQL blog:

http://sqlservercode.blogspot.com/

Personal Blog:

http://otherthingsnow.blogspot.com/