An XML Implementation: 9 Months and 9 Lessons


June 2002

An XML Implementation: 9 Months and 9 Lessons

CIDMIconNewsletter Valerie Yates, Director, MochaStone Consulting

As Manager of Information Development in an optical networking startup, I guided the implementation of an XML-based authoring, publishing, and content-management system. The process took 9 months from the moment I began seeking input regarding customer documentation strategy from the organization in January 2001 until the infrastructure for the Information Development team stabilized in October of that year.

I started working at the startup in early January 2001. Product requirements had yet to be defined; I was the first and only member of the Information Development department. I was faced with a blank slate.

My first task was to establish requirements for customer documentation. These requirements would drive the strategy, methodologies, and tools I would set in place for the department. I began interviewing senior management across all functional areas.

Central to my decision to implement XML-based documentation was the executive team’s interest in an eventual portal approach to customer support. In this environment, customers and partners would be able to dynamically “build” documentation according to their requirements. For example, an individual interested in the documentation for a specific product or type of information, such as troubleshooting, would request and download only that documentation. It seemed to me that XML, which attaches metadata to content, would pave the way for such an environment.

I secured executive approval, a lean project budget of $100,000 Canadian Dollars ($50,000 short of the sum I had hoped to secure), and developed a project schedule. The last two elements I determined based on research and preliminary vendor interviews. I did have misgivings about venturing into unknown territory; however, my team, which was beginning to take shape, was highly motivated as well as technically adept and intrepid. If anyone could do this, we could.

I chose Arbortext Epic Editor because of its reputed robustness and its profiling capabilities (profiling is a way of attaching information to information). For a content-management system, I chose Lightspeed’s Astoria (formerly Chrystal Astoria). Astoria because it was all our restrained budget would allow and it features a bridge to Epic.

By the end of April 2001, the products were installed. The core team of four information developers was in place, and basic training was completed. Our challenge was to successfully run a publishing pilot by July 31, 2001. We had three months to set up a complete infrastructure-to analyze and define our information needs and structures.

Our infrastructure required the following, in the order listed:

  • an information model to categorize types of information and where they appear in a document suite
  • a profiling strategy for attaching metadata to the information to facilitate access
  • a Document Type Definition (DTD), which provides the rules for XML documents
  • stylesheets for each output type to define the appearance of our deliverables

I was confident in our ability to define the information model and the profiling strategy; the DTD and the stylesheets I farmed out. Unfortunately, I did so to a vendor who significantly misrepresented the effort required to develop these elements. We found ourselves with no more than the foundations of a DTD and a project budget that was now deeply dented by software, installation, training, and development costs. A possible solution was to resort to the relatively inexpensive, out-of-the-box DTD and stylesheets that Arbortext offers; however, these did not align with the corporate look-and-feel standards nor with our content prototypes. In the absence of more funds, we had little choice but to do the work ourselves.

I established technical specializations for the project: an information architect, a DTD coordinator, and stylesheet developers. These specialists set about the daunting task of learning highly technical subjects while going about the business of documenting a large and complex solution in a startup environment.

July 31 loomed before us. Stress mounted: the team was fully committed to infrastructure development, but content development was falling behind. In addition, we discovered gaping holes in the technology. For example, Epic Editor does not provide full cross-referencing functionality. I was obliged to wrestle free an additional, unbudgeted $17,000 in consulting services to fix the problem.

With a push from the team, we successfully met our publishing pilot milestone. Information developers at last returned to their content-development tasks and began putting theory into practice. Using the system, however, uncovered the need for numerous refinements and changes to our DTD and stylesheets. We found ourselves in an interminable cycle of fixing, compiling, testing, and propagating fixes. We’d routinely break the system. Productivity ground to a halt as information developers once again turned into full-time XML specialists. I was obliged to call a halt to all but critical fixes; all other fixes would have to wait until after Release 1.

I was still recruiting in the late summer and early autumn. Productivity further suffered as new staff learned the unfamiliar toolset and veteran staff provided mentoring and assistance. Costs escalated again, unexpectedly, as we discovered that Astoria licences were not concurrent, despite being marketed as such by Chrystal. We had no choice but to purchase a license for each additional user, at a cost of $6,000 per license.

While our DTD and stylesheets had at last matured and stabilized by early October, we were plagued by software bugs that corrupted our content. Reporting these problems to vendors, applying patches, and performing cumbersome workaround solutions consumed precious resources in our small team and put into question the promise of enhanced productivity. To make matters worse, we were disappointed to hear near the end of 2001 that Chrystal was leaving the market.

Notwithstanding our difficulties, we remained on target for our deliverables and took great pride in our accomplishments. Thanks to stellar teamwork and technical wizardry, we set up an unfamiliar and difficult infrastructure nearly single-handedly, despite a budget, a schedule, and staff resources that I realized in retrospect were all inadequate. We were using a state-of-the-art authoring and publishing environment-an environment that is all the rage in the technical communication field.

What are the lessons learned from this experience? Whether you are contemplating an XML implementation for a new or legacy project for the first time, I hope that you might benefit from some of the following hard-earned tips.

1. Secure a Generous Budget

You will need a budget that will support not only your software requirements but also consulting and training services. Analyzing and defining information structures requires a significant up-front investment. For this reason, consulting services at the beginning of a project may well exceed your initial software costs.

Keep in mind that an environment is seldom static. Company products can change frequently and rapidly, as can documentation deliverables and standards. Unless you have resident expertise, you will have to employ consultants to effect significant revisions to your infrastructure. Your budget must be able to support such maintenance costs.

2. Obtain Consultants

Work with a consultant from the very beginning of your project. A consultant can help you determine a sound budget and can guide you through the process of tool selection more objectively than a salesperson can and more effectively than you can on your own. An experienced consultant will have a wealth of client experiences to draw from, many addressing the same issues that you have, and they can warn you about pitfalls.

Choose a local consulting firm if you can, particularly for a long-term relationship. Travel costs quickly add up. Before you choose a firm, ask for client references: an unprofessional firm can put your project into jeopardy.

3. Define a Realistic Schedule

Expect a planning and implementation schedule of six to nine months for a new project, double or more for a large, complex legacy project that requires conversion. Don’t try to do without important milestones, such as a publishing pilot, because cutting corners translates into increased costs and project risk.

The more tailored your environment, the more time you will need to analyze, define, and develop it.

As I mentioned in “Secure a Generous Budget,” an environment is seldom static. Make sure that your documentation project schedules allow for up-front revisions to your infrastructure.

4. Keep it Simple if You Can

If you do not have to satisfy specific content requirements or corporate standards, consider minimizing effort by going as out-of-the-box as possible. For example, use the DocBook DTD: it provides an XML vocabulary that is well suited to hardware and software user guides, and it is open source (which means free). If you use DocBook in an Epic implementation, consider purchasing Arbortext’s DocBook stylesheets. This combination will get you up and running quickly and inexpensively.

A customized solution, however, is the reality for many technical communication groups; a one-size-fits-all XML solution is a rare thing indeed.

5. Network

Talk to technical communicators who have worked in or set up an XML authoring and publishing environment. Find out about gaps and glitches the easy way; don’t expect a sales person to let you know about product pitfalls or whether there might be a mismatch between your requirements and their solution. Ask technical communicators about the specific issues that they hoped to address with an XML-based system and about their return on investment (ROI).

Ask a potential tool vendor for direct references to at least two customers.

6. Create Specialists

Specialists are team members who are dedicated to a technical and functional specialization. For example, you might assign the information model and the DTD to the information architect. You’ll also need to assign stylesheets to one or more stylesheet developers.

Specialist roles avoid eternal dependency on external consulting vendors. Depending on external consulting services for all changes-from changing font or page break specifications-is ineffective and costly.

Ready-made XML specialists are rare creatures and command high salaries. Remember that creating a specialist takes training and time and that training comes out of your budget. Remember also that specialist roles require a critical mass in a team. A small team with large deliverables, such as the team featured in this article, will support specialist roles with difficulty.

In the absence of specialist roles, make sure that you have a close relationship with a local, dependable consulting firm. You will also need a staff member whose part-time function will be to serve as a liaison with this firm.

7. Obtain IT Support

Make sure that your IT department can and will support your environment. If a content repository is in the plan, you will need administrative support, daily backups, upgrades, and possibly help with remote access.

8. Prepare the Team

If you do not yet have a team, hire carefully. Qualities to look for are technical aptitude, problem solving, flexibility, and a keen interest in new or different ways of developing technical documentation. Experience using structured templates is an asset.

If a team is already in place, prepare it for the transition, particularly if a paradigm shift is in the works. Buy-in from the team will help ensure success.

9. Keep Expectations Realistic

Keep your expectations and the expectations of upper management realistic concerning return on investment, particularly during the first project cycle or two. Claims made by vendors concerning ROI may well be exaggerated. Keep project metrics to help you determine whether XML helped the department achieve process efficiencies, should upper management come asking.

Remember that an XML authoring and publishing system does not guarantee excellent documentation. A toolset, after all, is only a toolset. XML merely provides an alternate way of authoring, publishing, and retrieving content.


An XML implementation requires far more than a purchase order for a set of tools. It requires careful planning and implementation. An XML environment requires considerable consulting assistance during the planning and implementation stage and possibly on an ongoing basis to sustain it. A well-padded budget is essential. An XML environment also requires a team that is large enough to sustain specialist roles if you wish to eventually wean the department from constant consulting assistance. A big budget and a large documentation team is usually the signature of a large company. Unfortunately, XML-based documentation is at the moment out of reach for most small and mid-size companies.

XML is an early adopter technology, particularly in the documentation field. It can only get better, easier to use, and less expensive as time goes by. CIDMIconNewsletter

About the Author