Creating Product-Specific Help Using XML
When an application is highly configurable to best meet customer needs, how do you write documentation that will continue to match the application? Technical communicators at Ontario Systems are using three strategies to meet this challenge.
Ontario Systems provides innovative hardware and software solutions to the industry’s leading receivables management companies. The company’s healthcare clients are among the nation’s top 100 hospitals, and our third-party receivables management clients include six of the top ten firms in the industry.
To maintain our leadership in this market niche and allow our company to expand into others, Ontario Systems announced that we would release our next generation of products in a “highly user-configurable application environment.” This environment would provide Ontario Systems’ clients with access to powerful component-building tools, allowing our company to customize products to suit nearly any of the workflow demands of our own international and domestic customers.
Because clients would be able to change the look and behavior of our application, the technical communicators determined that our documentation system should be as flexible as the application. This primary goal led our technical communicators to identify three tactical goals for the documentation system:
- assemble it based on installed application modules
- deliver it online from the application
- provide a way for our clients to change our delivered documentation, as well as incorporate their own components
One of the most important elements of this documentation strategy was that documentation would be written as relatively small “components” that could be assembled as needed to produce larger documents. These components would be included in the application and attached to the application modules that were delivered.
Because we would deliver the documentation electronically, the components could be assembled into requested documents based on the delivered configuration, and the documents would be accurate as long as the application was not modified.
To help our clients reflect their changes to the application in the documentation, Ontario Systems planned to provide a method for our clients to document the features they created or modified, as well as a way to integrate their documentation with ours.
If successful, this goal would allow Ontario Systems to meet a long-standing customer request: “Give us the ability to document all of our business processes in your application.” This request occurs because some of the steps of our clients’ business processes do not involve the computer, even though they merge with the computer processes. For example, the current FACS product is used to pursue accounts through the legal system. Some of the steps in the client’s process actually take place at the courthouse or an attorney’s office. Because these steps merge with steps performed on the computer, our clients would like to include them in the documented procedure. However, because these steps are different for every client, the client must be able to add to the documentation themselves.
When we began to consider the technology options, the technical communication team clearly needed a way to treat information content like data. The team wanted to select and control the documentation content in the same way we controlled the application. When researching technologies to support Ontario Systems’ documentation goals, the team realized we would need a way to manipulate documentation components programmatically: to locate and assemble the components based on a user command.
One possible technology that could meet our goals was SGML (Standard Generalized Markup Language). Yet, while SGML has been a documentation standard since 1986, it has not been widely accepted because SGML tools are generally more expensive than other tools for text editing and SGML is very complex to implement. However, SGML does have the technical characteristics that Ontario Systems wanted. In particular, SGML supports programs that locate and assemble document components.
During our investigation, a related technology, XML, emerged. XML (eXtensible Markup Language) has similar benefits to SGML, but it is less complex and less expensive. Also, due in part to these factors, XML is more widely accepted. As Ontario Systems researched XML, the development team decided that XML fulfilled our requirements, and that the company should continue to investigate XML’s potential.
After some proof-of-concept development, we moved an XML document into a prototype of our new application and used application calls to display the document in Microsoft Internet Explorer 5.5 (IE5). This delivery mechanism extracted and merged information content from the application database, applied an XSL style sheet, and delivered the resulting document to the browser.
As our documentation project progressed, the Technical Communication department began to plan the changes that would be required in our work processes. As a part of our planning process, we hired an outside consultant to help us analyze our documents and determine the suitability of the document structure for a single-source environment.
Fortunately, Ontario Systems has been using a consistent format for user guides, reference manuals, and other information products for several years. Ontario Systems has also been using style guides for some time to control the writing styles used by its group of about twelve writers. For this reason, the document analysis work was relatively easy to complete, although the company decided to make a number of structural changes to improve document quality.
Our consultant also contracted to help us write our Document Type Definition (DTD), which is the controlling document used by the XML editor to determine whether a document is valid or not. A valid XML document follows all the structural rules built into the DTD. The consultant’s help reduced the amount of time needed to write a usable DTD.
Our User’s Editorial Environment
As we considered ways for our clients to make changes to our documentation and add their own documentation components, we were sure that many of our clients would not want to learn XML or incur the expense of buying an XML editor. We decided to provide, at least initially, a simplified editorial environment.
Our plan, at this time, is to provide Web forms that mimic a simplified version of our DTD. An initial Web form will ask the users to specify the application feature for which they want to add documentation. Once the feature is specified, another Web form will display the current help (if it exists) with a series of fields to complete or change. If the feature has been added by the client, and they have not yet added documentation, a blank Web form will appear. Our client will then edit the documentation in the Web form fields or add new information. When the client submits the Web form, our application will parse the documentation and store it for presentation when help is next requested.
As an enhancement, our application will include a suite of editors for a variety of features in the application. When that enhancement is available, we plan to integrate a full-featured XML editor.
During the writing process, our writers grappled with a significant concern. How were they to write components of documentation that would read coherently after they were assembled into an integrated document? Our current approach is to write everything in present tense and make use of a stringent style guide that helps our writers write in a consistent manner. Our writers are used to, and support, this approach because we have been using a style guide for some time prior to this project.
Once fully in place, our system will allow us to deliver an application that our clients can modify to process accounts in nearly any part of the workflow process. They will be able to record and track whatever account data is important to their process and control workflow based on that data. Furthermore, using the Ontario Systems documentation system, our clients will be able to maintain the accuracy of their documentation by adding their own components and integrating them with the ones provided with the application.
Those considering implementing an XML single-source system might consider the following recommendations:
- Take time to learn the technology. Do a great deal of reading and studying. Elliotte Rusty Harold’s XML Bible provides very useful information. (See sidebar for reference information.)
- Allow adequate time for planning and preparation. Things always seem to take more time than you expect.
- Institute standards-based writing in your Technical Communication department. Implement style guides and structured writing before you start this type of project. They will improve your current documentation and prepare your team for the change.
- Involve your writers in the design and planning phases. If the writers support the project, it will go more smoothly.
- Select good tools and vendors that can provide good customer service and support. You will need them.
- Allow plenty of time for testing and prototyping. Without a prototype, you can’t be certain that your process will work. And, the prototype will reveal problems you didn’t think about.