Re: documenting a database

[Geoff Lane <geoff -at- gjctech -dot- co -dot- uk>]

On Tuesday, May 15, 2007, John Posada wrote;

>> If you're documenting a database, your audience will probably
>> expect to see things like an EAR model and/or a schema. They 
>> might also need the business rules being modelled together with 
>> the mapping between the rules and the entities, attributes,
>> relationships, and constraints. You might also need to understand 

> With all respect to Geoff, screw all that. Get a program made for
> creating data dictionaries (that's what you are creating), run the
> program, and deliver the output.
---

You might well use such tools, but if you don't have the background
knowledge you're setting yourself up for a fall.

Documentation of a database is normally a lot more than just producing
a data dictionary. Most DB docs I've written have needed the ability
to be able to read data models, make sense of them, and map between
them and the schema. If you've never seen an EAR model, how are you
going to make sense of them - especially if your search of the 'net
turns up one convention but your software tools output another. BTW,
the data model should already exist - because it's an output of the
analysis phase of most projects - and you can get the schema in many
DBMSs by generating a dump even if there isn't a specific tool. But
you've got to be able to make sense of these otherwise how do you
expect to be able to impart the information to your readers - who
could be very knowledgeable?

Now I suspect that someone who has to ask how to begin to document a
database hasn't got the background knowledge to do the job
competently. If they did have a suitable grounding they would already
have seen several examples and so would be unlikely to be in the
position of "not having the foggiest idea how to get started."

-- 
Geoff

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.