A DITA Wizard

This article presents a case study of the development of a DITA-based "wizard" to dramatically improve the efficiency of writing proposal documents. The "Proposal Generator Wizard" was developed by HyperWrite for TACTICS Consulting.

By Tony Self

Scenario

Two of the oft-quoted benefits of DITA, the Darwin Information Typing Architecture, are "single-sourcing" and "content re-use". These benefits do not only apply to the commonly-accepted definition of technical documents, but to many other forms of documents from outside the technical communicator's realm. Likewise, although DITA is intended for "authoring, producing, and delivering technical information", it can be used outside just "technical information". DITA is an architecture for designing, writing, managing, and publishing many kinds of information in print and on the Web.

TACTICS Consulting is an Australian-based consultancy company that develops information and learning solutions, and is the sole Australasian distibutor of the Information Mapping® methodology. It has offices in three cities. Much of TACTICS work originates from tenders. The strike rate for winning tenders in a very competitive market is relatively low, and the preparation of responses to requests for tender (RFTs), requests for information (RFIs) and expressions of interest (EOIs) is a thankless task. And a time-consuming, expensive and exacting task.

Management at TACTICS was looking for ways to further raise the quality and consistency of the company's responses. Different offices had developed different approaches and different formats, and the time required to produce responses was such that TACTICS had insufficient time to respond to many requests. The company wanted to find a way to improve the efficiency and lower the cost of proposal and response document preparation. TACTICS saw DITA as a potential tool to help achieve these objectives.

Although TACTICS is a forward-looking company not shy of embracing new ideas and technologies, it did not have in-house DITA expertise. For this reason, a team from TACTICS approached Melbourne-based HyperWrite to lend some help. HyperWrite is a hypertext solution company with a focus on emerging techniques and technologies, and with DITA and other XML experience. With an abundance of Information Mapping experience, TACTICS staff knew information typing and content chunking backwards. A project to develop a "single-source" proposal generation workflow was started; the result was ultimately known as the "Proposal Generator Wizard".

The Problem

Proposals and other response documents had previously been prepared in Microsoft Word, with any new proposal based or modelled on an earlier proposal. The sales team member preparing the proposal would browse through previous documents to find a close match. This browsing required opening and analysing as many as ten earlier documents, and sometimes relied on memory. If the matched earlier proposal was not recent, it may have contained out-of-date information or incorrect figures.

The person preparing the proposal would then have to pick through the document to find and edit this obsolete information. Irrelevant information would also have to be deleted, and other information might be added by cutting-and-pasting from other potentially incorrect documents. Occasionally, obsolete financial and costing figures would find their way into proposals. The nub of the problem was that the starting point for preparation of a proposal was a potentially incorrect document.

To ensure the high quality of its proposals, TACTICS had to spend a lot of time proof-reading and double-checking the content and figures.

The schematic below illustrates the previous workflow.

The problem elements in the approach could be summarised as:

• arbitrary selection of "template" document
• obsolete information too easily incorporated
• errors perpetuated
• inconsistent format (look-and-feel and text sequence)
• slow and tedious process.

As more proposals were completed, the pool of previous proposals became bigger, and the harder it became to find the right model document.

Enter DITA

Being in the documentation and training industry, TACTICS were well aware of DITA and its potential for improving efficiency. The challenge was to determine whether it was a good choice for proposal generation. To be successful, a DITA-based solution would have to eleminate the arbitrary nature of selection of proposal content, prevent obsolete information being included, reduce the chance for error, and provide a more rigid document framework. And it would have to reduce the effort and time required to build a proposal.

Not only does DITA offer content re-use and single-sourcing, but it also incorporates the concept of separation of content from form. It was hoped this feature would provide a level of control over how a document looked by removing the ability of a proposal author to change it. DITA's topic-based approach seemed a good match for the modular nature of TACTICS' proposals.

The Solution

The wizard solution delivers a ditamap file for the proposal. That map file references a pool (or "repository") of DITA "topics", which are the possible components of a proposal. (Topics may be one sentence long, or ten pages long.) The map file is later transformed into a Word document using Elkera XML Print. That Word document is the deliverable of the "proposal generator product", which is the wizard, the templates, the repository, and the workflow process.

Project Aims

When the project was started, a list of objectives was drawn up.

• We want to reduce the amount of time taken to get a draft proposal going.
• We want to produce consistent proposals across offices:
  • consistent in content (wording)
  • consistent in structure (sequence of sections)
  • consistent in presentation (styling).
• We want the proposals to conform to Information Mapping® principles.
• We want the process of producing the draft to be relatively simple.
• We want to make it easy to update the content in one place.
• We don't want a fully automated solution, as all proposals must always be customised in some way.
• We want to use the repository of topics created for the proposals project for other purposes in future, such as in brochures or on the Web site.

The Wizard Described

The solution created is a small Web-based application built around a "repository" of DITA content chunked into comments. The repository (a directory full of DITA files) contains all the possible components of a proposal. The Web wizard is used to select the type of proposal and the topics to be included. The names of the available topics, and what type of proposal they can be used in, are stored in a simple Access database, which the wizard interfaces with. At the end of the selection steps, the wizard creates a master ditamap.

The master ditamap then gets passed to Elkera XML Print, which converts the DITA content to a draft proposal document in Word format. The wizard process ensures consistency and currency of the content, and cut two or three hours from the proposal process. The draft document still has to be modified to suit the particular requirements of the individual proposal; it is the process of generating the first draft of the proposal that the wizard addresses.

In essence, the wizard provides TACTICS staff with a standard approach for assembling topics into a draft proposal. Proposals are always based on the most current information in the repository.

It transpired that the bulk of project work was not in writing the wizard, but in creating the topic repository.

The Wizard Described

Project Tasks

The repository was created by analysing a large sample of previous proposals, and identifying all the possible blocks of content. The chunking was critical to the modularity of the approach.

The analysis revealed that there are five distinct types of proposal documents: long letter format, short letter format, e-mail, formal proposal in TACTICS format, and formal proposal in the client's format. Different sorts of content is used in different proposal types, although some content is used in all proposal types. One of the first steps in the project was to draw up a matrix of proposal types and content chunks.

Content chunks may end up being be used in whole or in part. For example, a proposal may include a resumé, or just the overview portion of a resumé. To make selection of components of a proposal simpler, it would be possible to select a DITA topic for inclusion, or a group of topics (a "ditamap" collection).

After identifying the chunks, and working out whether they were topics or collections of topics, the lengthy task of creating the DITA topics could begin.

JustSystems XMetal DITA Edition was chosen as the content editing tool. HyperWrite trained three TACTICS staff in basic XMetaL skills. Cutting and pasting from existing Word documents into XMetaL was considered at first, but it was decided to use the opportunity to review and re-write all of the content. This decision ensured that the repository started life with correct, up-to-date topics. The staff creating the DITA content, already expert in Information Mapping, found the transition to DITA an easy one. They were able to complete the bulk of the rewriting work without any external support.

The rewriting of the content topics took place over eight weeks at TACTICS. Concurrently, HyperWrite was working on the wizard. Because both parties were working to the DITA standard, the integration of wizard and content repository was seamless.

The last task was to perfect the conversion of the wizard-generated ditamap and the referenced topics in the repository into a Microsoft Word document. This function was to be performed by Elkera XML Print. Elkera is a Sydney-based software company specialising in developing automated single source document publishing solutions. XML Print converts XML files (including collections of DITA content) into Word format using a unique, template-driven style rules approach. DITA elements are mapped to Word styles by modified a Word template and then processing it through a "Stylesheet Compiler". The Word documents produced are fully featured, with automatic numbering, linked table of contents and named styles. Some customisation of the XML Print style rules was necessary to ensure the documents conformed to Information Mapping® conventions.

The Wizard-based Workflow

Technical Description

The wizard is an ASP.Net application, hosted on Microsoft Internet Information Server (IIS), and references an Access database. The wizard pages are delivered to the browser as XHTML; no plug-ins or Java applets are required. The server dynamically builds the six "steps" of the wizard:

1. Choose the type of proposal.
2. Choose "generic" sections (sections that can be included in any type of proposal).
3. Refine generic sections (choose which parts of the selected sections to be included).
4. Choose "specific" sections (sections that are appropriate for the type of proposal selected).
5. Refine specific sections (choose which parts of the selected sections to be included).
6. Generate the master ditamap.

The Access database stores a list of items available for inclusion in a proposal, the corresponding file names for the items, and the type of proposal the items belong in.

The two Choose section steps retrieve a list of available items from the Access database. In most cases, the referred items are ditamaps, but they may be individual DITA topics. The two Refine section steps retrieve a list of items (sub-items, if you prefer) from any selected ditamaps. Selection options are displayed in an expandible/collapsible tree structure. By ticking checkboxes next to the available items, the proposal author can choose what items to include in the proposal.

The final step generates a ditamap referencing all the selected items. This represents the upper level table of contents of the proposal. The generated ditamap can then be saved onto a network drive, from where the Word document is generated through XML Print. Because the ditamap contains pointers to content, rather than content itself, the relative locations of the DITA content is important. TACTICS configured the server so that the same repository of DITA content is used by both the wizard and XML Print.

The DITA content repository is maintained through XMetaL by the marketing team. Sales staff generating proposals do not have write access to the repository, and cannot accidentally modify the underlying proposal content. They can only modify the text once it has been generated into the draft proposal Word document.

Phase 2

The wizard is the first stage of a bigger endeavour. A principal of single-source is "write once, use everywhere". The repository of content has uses beyond proposal generation. For example, the sort of information that goes in a proposal may also be used in a marketing brochure, on the company Web site, and in an annual report.

The second phase of that endeavour is now underway; it will use the DITA topic repository as the content source for the TACTICS Web site. More topics will be added, and it will be necessary to add a content management or version control system to keep track of the files.

The diagram below shows how Phase 2 works alongside the wizard.

Phase 2

Summary

The Proposal Generator Wizard allows a draft document to be rapidly assembled using a repository of content modules. Using DITA for the content repository, and as part of the item selection process, allows the use of single-source principles when creating essentially unique, but modular, proposal documents. The process has greatly reduced the time taken to produce proposals, lowered the risk of error, and delivered consistency of structure and presentation.

TACTICS can now better control the currency of the information being prepared, and a tedious and onerous task is a few simple steps. Further, the company has built a great deal of in-house DITA skills through this practical and innovative project, skills that they can now apply to their clients' projects.

For a further information, view a simulation of the Proposal Generator Wizard.

Article in CIO Magazine by Su-Laine Yeo

---

Links

• simulation of the Proposal Generator Wizard (http://www.hyperwrite.net/Tactics/PropGenMovie/default.htm)
• Article in CIO Magazine by Su-Laine Yeo (http://advice.cio.com/su_laine_yeo/11052/better_contracts_and_proposals_with_dita)

---