Re: How to document a DB

Thomas T wrote:

>"Rick Denoire" <100.17706_at_germanynet.de> wrote in message
>news:d1lclvgbkip49ue4ce7jhi7logui2brpb6_at_4ax.com...
>
>
>>Perhaps this is a silly question. I have got the task of documenting a
>>DB. I keep this DB up and running (backup, reorganisations,
>>configuration, etc.) but I am not familiar with the applications
>>running based on it, neither am I familiar with the schema and
>>relations (i.e., I don't understand the real sense of data contained
>>there in - although I could).
>>
>>If I compile a document containing key information about tablespaces,
>>backup procedure, security issues, stability... that would raise
>>eyebrowses. What is expected is a description of the DB based on data
>>dependency, workflows, basic data structures from the point of view of
>>the users, when data is loaded and who uses them the most for what,
>>and, most important, what is to be considered when making any changes
>>in order not to break anything.
>>
>>Since I am not the first one in life with such a task, perhaps someone
>>can point me to a standard procedure to setup this documentation. Or
>>give me a hint about tools helping me in this question.
>>
>>We use Oracle 8.1.7 on a Sun E3500/Solaris 7 at the moment.
>>
>>Thanks a lot
>>Rick Denoire
>>
>>
>>
>
>I'd be interested to know as well. I created a database application over
>the winter; and I have my developer notes, but that wouldn't really help
>anyone other then a developer/DBA.
>
>One thing you might want to look at- the only thing "new" I picked up from
>my database class at a local university (it was 99% theory)- is an E-R
>diagram; entity-relationship diagram. See some info about it here (found by
>doing a google search for "er diagram database")
>http://www.cs.sfu.ca/CC/354/zaiane/material/notes/contents.html It might
>look impressive on an overhead projector...
>
>Basically it says an entity (thing/person/etc) has a relationship to
>another. Such as a person might be related to an account, a company might
>have a contract with another company, a job performed might require a
>payment, etc. It's supposed to help development of a database- i.e., if you
>can solve a query by walking an E-R diagram, your database design is good.
>Of course, it's just theory again. Next time, somebody remind me not to
>take classes in things I already know!
>
>But like I said, this is mainly for developers. It'd be interesting to see
>what a formal write-up of a database might look like. The most I've seen
>has been a binder filled with table descriptions; and they've been archaic,
>at best- and probably done that way on purpose. I've found out more just by
>querying all_tables and all_triggers!
>
>-Tom
>
>
>

I've yet to ever find the developer that looked at notes before diving into someone else's code. I know there must be that exceptional person out there somewhere ... but I've yet to meet them.

The reason is that (A) most documentation is written by people whose primary skill set is not in writing technical documentation and (B) from my experience the documentation is NEVER maintained so it doesn't accurately reflect change that have taken place over time.

I think your instinct with respect to ALL_ objects is a good one. To that add ALL_dependencies. But in the end nothing replaces a careful read of the actual production source code.

-- 
Daniel Morgan
http://www.outreach.washington.edu/ext/certificates/oad/oad_crs.asp
http://www.outreach.washington.edu/ext/certificates/aoa/aoa_crs.asp
damorgan_at_x.washington.edu
(replace 'x' with a 'u' to reply)