Retrospective Documentation of Relational Databases

Many databases have only limited documentation, often cryptic and difficult to access and use, written for programming and tech support staff not for business users.

Accessible and high-quality documentation of data content and business purpose, as well as explanation of technical structure, is one of the keys for unlocking additional value through data analysis and mining projects. SMH Systems are expert in online documentation and in relational data management; we can develop online documentation for your databases covering all of:

• database technical structure
• business-oriented explanations
• content, quality and usage considerations.

Our documentation product The Manuals Machine is outstandingly well-suited to database documentation. It supports all the types of content that comprehensive documentation for your relational database might require:

• tabular content to present the table structures and show sample data
• narrative text content for descriptive material
• graphical content for entity-relationship diagrams
• PDFs to include extracts of the database server documentation, or the application vendor's manuals.
• text files to store setup and query scripts.

All of these organised into a single high-performance book-like structure with easy-to-use table of contents and alpha index, and with comprehensive internal hyperlinking.

RDB engines store definitions of the technical structure of the database and its tables internally, in a "system catalogue" which is available for query. SMH Systems has developed queries and scripts to convert table details extracted from the system catalogue into XML documentation pages - as illustrated at left Should the database structures be updated the scripts can be rerun to refresh the documentation within minutes

Descriptive sections to capture the knowledge of systems developers, application administrators and experienced users can be quickly prepared using the Manuals Machine Author/Editor. Illustrations generated by diagramming and reverse-engineering tools are simple to integrate, as are extracts from external documentation from database vendor, application supplier or industry standards. If wished the documentation can include samples of data values, outputs from sample reports and queries, and archive copies of setup and query scripts.

Comprehensive documentation for a large database can extend to many thousands of items in a variety of styles and formats. The Manuals Machine can be used to organise and index this content, which is instantly available to designers, developers and data miners as a highly-accessible online resource. The Manuals Machine's customisation features are used to embed special XSLT stylesheets, which automatically generate hyperlinks between related pages. This provides simple and consistent navigation across the various technical details extracted from the catalogue, and to added narrative.