Left-field examples

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!

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.

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

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.

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

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.

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.