TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I have been working on documenting a large database system that serves as
the backend for an OLTP financial services system since roughly May. At this
stage I have documented about 2000 pages of tables, stored procedures, and
interdependencies among them all. I did a thorough search of database
automation systems earlier in the year, and what I found was that
off-the-shelf products don't exist. Visio does a lot; Erwin is very powerful
(and very expensive - my shop doesn't own it); FMS has a SQL 2000
documentation system that's useful but not for what I wanted. I concluded at
the time that I could automate Visio by using Visual Basic for Applications
and come up with a killer system, but I didn't have the time to learn that
and get the work done, which was to document the database.
Here's how I do it: I use RoboHelp HTML to compose the pages. This product
does a good job of generating a web site that has an index, a table of
contents, and a search function. The results are a bit slow on the current
server I am using, but they are adequate. I use SQL 2000 Enterprise Manager
and the Query Analyzer to look at the tables and the stored procedures. I
have to look at both the table schemas and often the data in the
development, QA, and production databases in order to understand precisely
each field: I provide the field name, information about the data type of the
field, and a description. I use stored procedures we have developed in house
to learn what dependencies the tables have (for example, what stored
procedures make calls to specific tables). I use the query analyzer to get
an exact picture of the parameters that a given stored procedure require as
input or output. I can select, copy, and paste those parameters into
FrontPage, convert the text to a table, and copy the html into my RoboHelp
pages. Some stored procedures have no parameters, some have a hundred.
Likewise some tables have no dependencies (stored procedures, triggers,
views), while at least one I have documented has more than a thousand. I
have a system with about 700 tables and 2000 stored procedures. Many of the
stored procedures are obsolete, and I document that as well.
The big advantage of this way of documenting the system is that I am getting
a first hand, very close look at the entire back end. I am virtually the
only one in a department of about 15 developers with this kind of knowledge.
On the other hand, the big disadvantage of this way of doing it is that the
system is a "moving target," so that a database I documented three months
ago will have significant changes today. Fortunately I have at my disposal
DBA authored stored procedures designed to document (or analyze) changes to
the schema and to the stored procedures, and I can use them to help me keep
the system up-to-date, but what I would really like to have is something
like DocumentX!, a product from Innovasys that is very good at documenting
VB developed applications. Richard Sloggett of Innovasys has told me they
are working on such a product for SQL 2000, but so far it has not been
released (or it has been released in a preliminary or beta version). The
great beauty of DocumentX! is that it allows you to create a Web site from
the source code, mirroring the precise structure of the original project (in
Visual Basic) and allowing the tech writer to add any descriptive text or
other illustrations required. Each time you regenerate the Web site from the
source, you get an updated version based on the source without losing any of
the additional materials added by the technical writer.
Visio, ERWIN, and even SQL 2000's diagramming solution, are excellent at
showing the primary key and foreign key relations among tables; however, it
would not be practical in most of the databases I have been working on
because they are too large and complicated. One would need a large plotter
type printer to represent even part of the table structure, and show the
connections in a way that was legible.
The solution I have come up with is limited also because this is only a part
of the picture: where are the requirements documents (most are in Word),
where are the applications documentations, where are the design documents?
The solution is only partial, and more work needs to be done. I know of only
one really integrated documentation solution (from Rational software), but
for that to work the development shop needs to be fully "rationalized," that
is using Rational development tools.
If anyone else has discovered an automated database documentation system,
I'd love to hear about it.
Andrew Lakritz
Senior Technical Writer
Ruesch International
Planning to attend IPCC 01, October 24-27 in Santa Fe? Sign up by
October 3 and get a substantial discount! Program information,
online registration, and more on http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.com +++
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
