What is your preferred document format for documenting databases

Question

I am in the process of writing an application which, among other functionality, generates MediaWiki documentation of an MSSQL database (objects, tables, table data).

My question is which document formats you prefer, or are required to produce. I have too many ideas to follow, so your answers should set my priorities ;)

(I know there are other documentation-related questions on SO, but they mostly deal with how to generate documentation (I know how to), and do not ask for specific doc types or platforms)

Edit: Thanks for the comments. Actually I have table relations already, since I parse foreign keys. However full cross-reference may be a bit trickier ;)

However the question was meant to ask for the document types, such as Word, PDF, ODF, whatever. What are your professional requirements or preferences?

Update: Overview of generated documentation

Answer 1

It sounds like you have already decided on a document format, which is HTML based on MediaWiki markup.

Also you should generate Entity-Relationship Diagrams which are useful additions to database documentation (though ERD's don't tell the whole story either).

Do you mean document organization, i.e. what headings and content should be included in each page?

Here are some suggestions:

1. Table Structure

   • Column names, data types, constraints
   • Meaning and usage of each column
   • Extra logical constraints in triggers and application code
   • Indexes defined

2. Relationships to other tables

   • Tables dependent on this one
   • Tables this one depends on
   • Notes on special or implicit relationships, that have no enforcement through database constraints

3. Usage of table

   • Usage in stored procedures
   • Usage in application code
   • Usage in views
   • Who has read and/or write access; SQL privileges of each user or role

There are other questions at StackOverflow that are very close to this one.

• "How to document a database" is a very similar question to yours, since it's specifically about wiki documentation solutions.
• "What are the best ways to understand an unfamiliar database" may give you some good tips, as you are creating documentation that would help someone in that situation.
• "How do you document your database structure?" is related but not as closely, because it's about putting documentation into the metadata itself.

Answer 2

You might want to have a look at what the commerical vendors do regarding this. As Bill said, you certainly need an ER diagram. Commercial products to look at could include Embarcadero ER/Studio, Red-Gate SQL Doc, Power Designer and others.