To main heading
Headshot of Patanjali Sokaris

Pondering the universe

Science & technology

Left-field examples

Here are some examples of my left-field approach to creating documentation.

Big system with little documentation

For a 14-year-old system with very little documentation, the client was losing the contract for providing maintenance for it, and so had to provide handover documents, in 16 months.

The only documentation was source code files, being in C, Delphi, Uniface, PL/SQL and Crystal source files. Uniface is Oracle-based, and the client had 650 forms implemented just in it. I only had one part-time SME to help me. At an optimistic manual 5 pages a day, I would only be able to produce about a 1000 pages in the time allowed. That definitely wasn’t going to cut it, so automated it was to be!

I basically needed to provide two parts for a solution:

  1. 1.Extractor of program elements from source files into an Access database
  2. 2.Creator of Word documents from Access database SQL queries.

Since the system used an Oracle database, I chose to create the second part first, as it was all that was required to create the database schema documentation, after copying it into an Access database. I wrote it in Word’s VBA, and extensively used Word’s Autotext facility as formatted specifications of which SQL query in the Access database to use, the layout of its field values, and possibly other Autotext entries to use within it.

Basically, the process involved putting master Autotext reference text in a document, and invoking the VBA macro to recursively expand them into the full content of the document. It actually looked quite cute as it threw in line by line, if I enabled it to show updating.

The extractor used Access’s VBA to read in selected source files, recursively identify program elements using regular expressions, putting them into a hierarchy in an XML file, then extracting data from that XML file into database tables.

The SME typed descriptions into an Access table to be merged into the documents. The Uniface forms had over 23,000 fields, of which there were only 6,000 uniquely named. I preloaded those into an Access table, for which the SME filled in generic descriptions, but added a record with a form name if a unique description was required. That saved them a lot of time.

The solution used about 150 SQL queries, and produced 15,500 pages of documentation, which amounts to 58 pages per day, more than 10-fold better than doing it manually.

An example of an output that would have been extremely tedious to do manually across thousands of entities in different source files, is the cross-usage listings, which were especially important given the upcoming redevelopment that was planned, where impacts of intended changes needed to be assessed:
Page of entity details automatically generated from extracted program source code

If the client had wanted HTML files as output, I would have just used XML and XSL.

A UML too far

I was asked to produce a huge UML diagram of a client’s object-relational database schema. Realistically, that would have taken months, while they were still making changes to the database.

Large diagrams are tedious to optimise visually, and hard to take in. Plus, there is a lot of information that cannot fit, like class member and field descriptions.

The database used an SQL like language called DQL, one command of which generated all the DQL commands to create the current schema. I built a VB utility that parsed those commands into an XML, from which a hand-built XSL file transformed it into a fully hyperlinked HTML file that centred on one entity at a time, showing class inheritance and foreign-key trees, both ancestor and descendant, and field lists.

I later added the facility to add field and entity descriptions in a separate XML file, for merging in when the HTML file is generated. Missing descriptions were indicated. Once descriptions were specified, it only took 10 minutes to document a schema.

The team lead wished they had the utility when they were designing the database, as seeing it pictorially easily showed where it could be optimised. Future versions of the database would have included the utility, had the product not been canned through lack of sales.

A sample class diagram from the HTML file is:
Part of HTML page for one object automatically generated from SQL schema commands for an object database

Contracts bloody contracts

With over 600 pages of contracts covering a client's contractual obligations, I was given the task of producing a set of 12 documents, listing the obligations for each division, to be done within four months.

I used Word’s VBA to read in those contracts – after a temp had normalised them into plain text – into a Word table, allocating each obligation to divisions by keywords:
List of contract obligations
The utility also allowed modifying individual obligations, like editing their text, splitting them, or reallocating them to another division:
Dialog box for managing a contract obligation
The state diagram for the Status field of the Obligation record:
State diagram for contract obligation

I provided them with a complete set of documents in two months, and they had the value-added of being able to manage and print updated versions themselves.

Looking at it Rationally

One client had just changed methodologies, mid-project, to using the Rational Unified Process (RUP), so they wanted me to do a diagram that showed all the elements of the RUP universe.

This was obviously going to be a big diagram, with a lot of detail that no one was going to be able to take in. But even then, there was a lot of detail that was going to be left out.

Rational had a lot of documentation online, but none brought together all four groups of elements, so I took a different approach, and created an Access database, into which I cut-and-pasted details of each of the elements.

From there, I created a report that listed the hierarchies of elements, together with all their details:
Page from an Access report on Rational Unified Process (RUP) entity relationships

It took a few days, and the client preferred it to what they had envisaged, and what would have taken a lot longer.

What’s more, I sat next to the Rational consultant for the project, and they wanted a copy because there was nothing like it at Rational. Just goes to show that there is always something new that can be brought to the table.

  • Left-field assignments
  • Contact   Policies
  • Categories   Feed   Site map

  • External sites open in a new tab or window. Visit them at your own risk.
    This site doesn't store cookies or other files on your device, but external sites might.
    Help   Powered by: Smallsite Design©Patanjali Sokaris