This is an example of a large structured documentation project used for IT specifications and tech doc. We'd recommend this approach for retrospective documentation of legacy systems as well as new specifications. This case study demonstrates the major benefits of a structured approach based on XML, providing manageability of the process, ability to focus the authors on content not appearance, sharing of the deliverables through browser-based delivery, and version control.
Our client was a financial services organisation, who wished to outsource printing and mailing of materials sent to customers. SMH Systems was initially called in to provide project management for the transition, in the course of this work we discovered and solved a major document management problem.
The source system was a legacy IBM mainframe environment, whose batch runs generated files containing data for all mailers to be prepared and dispatched for the run.
The outsourcer's duties were to merge the data into customised documents, then print and dispatch these as a mailpack containing additional materials such as preprinted information forms and booklets. There were many hundreds of potential document types and mailpack inserts, depending on the customer's product, renewal status, payment status, residence location, etc.
The printshop had modern automated equipment for printing and for mailpack assembly and sorting; the problem was to specify the print formats and business rules to be used to prepare the customer documents and assemble the mailpacks, from the mainframe output file. The printing subsystem was expected to merge standard text and job parameters, and to handle a lot of the business logic, including insertion of default values, column totalling and page-by-page subtotals, and conditional text and data.
The documents had been prepared for over a decade on IBM intelligent printer systems, and most of the business rules for content and layout were embedded in the scripts that had been prepared to post-process Cobol program output for the intelligent print subsystem. Rules for construction of mailpacks were mostly loose-leaf instructions that had been prepared over the years for a service which had performed the assembly semi-manually.
The new printshop was able to reverse-engineer the scripts but could not commit to a reliable interpretation. It was necessary to document everything so that the users who 'owned' the application could review and sign off. A first attempt to document the requirement for just one product generated a 280-page Word document which couldn't even open on most of the client's desktop PCs! The logistics of specification distribution for review, and subsequent incorporation of changes, emerged as a huge problem.
Enter XML - we identified ten document types necessary and sufficient to carry the various information and specifications for the process. These included data feed production rules, data feed field-by-field format and semantics, customer document specifications, specification for component objects to be manipulated in the printshop's intelligent graphics systems, mailpack assembly specifications, and so on. An XML document structure was defined for each type.
We developed stylesheets to render each type of document in Internet Explorer 5, then dissected the 280-page Word document onto fragments matching the various document types and tagged them for the XML markup. Suddenly, the almost-inaccessible specification became available on the office network to all stakeholders, with updates becoming available online immediately they had been made.
Having achieved a modular specification, we were able to assign ownership and responsibility for content among the stakeholders. Business analysts were trained to author the XML source - a Y2K freeze on the client's SOE restricted the tools available to Windows Notepad and Microsoft's experimental XML Notepad, but they worked well enough given that the author had instant review of his/her work via their browser's 'refresh' button. Despite these primitive tools, authoring was highly productive because writers could concentrate on content without having to worry about controlling layout and appearance of their deliverables.
All documents were stored on a Windows NT network server. Subdirectories were used for the specifications for each of the client's core products, which typically required 150-500 files per product in order to document all the operational and customer service options.
The stylesheets generated hyperlinks to enable navigation of the specification and its internal cross-references. Drill-down to increased levels of detail was intuitive and fast. For example a business rule specification which referenced a field in the data feed would be displayed as a hyperlink, the reader could click-through to the data feed specification which would be automatically positioned to the details for the field in question.
The document repository also included PDFs, generated by the outsourcer printing systems, which provided examples of the intended customer documents. The stylesheets generated hyperlink access from the XML-based specifications to these illustrations.
Finally to assist review and revision, and to accommodate evolving business requirements, we included author, version, change control and sign-off information, plus the ability for readers and reviewers to browse between versions. All made visible through the XSLT stylesheets.