Re: documenting a database

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

On Tuesday, May 15, 2007, doc woman wrote;

> I've worked on procedures, guides, manuals, etc.. now I will be documenting
> a database and I have to admit I haven't the foggiest idea how to get
> started. Any advice out there for me?
---

Are you talking about a database, a database management system, or an
application that's based on a database or DBMS? If you don't know the
difference and it's not the latter, my honest advice would be to pass
the job onto someone who does because it will take you too long to get
up to speed.

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 how data anomalies can
arise (e.g. dodgy normalisation) and prod your SMEs so that they
either explain why something won't be an issue or restructure the
database.

If it's a DBMS you have to tell database-savvy people how to implement
the things with which they're familiar, and in their terms. You'll
need to understand entity and referential integrity, primary and
foreign keys, etc. You'll probably need to understand at least the
basic DDL and DML that the DBMS uses (often SQL) so that you can
quickly comprehend the extras that your DBMS adds. Many DBMSs also
have their own scripting language or provide one or more APIs - so you
might also need an understanding of the target programming languages.

However, if it's just an application and you're writing user docs,
neither they nor you really need to know the intricacies.

Sorry that I can't be more positive.

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