Volume 2

Issue 1

March 2005

Feature Article Case Study: Using DITA to Develop a New Information Architecture at BMC Software Wendy Shepperd BMC Software, Information Development Manager wendy_shepperd@bmc.com BMC Software is a leading provider of enterprise management solutions that empower companies to manage their IT infrastructures from a business perspective. Delivering Business Service Management (BSM), BMC Software solutions span enterprise systems, applications, databases, and service management. To better support the integration that BSM solutions provide, the Information Development organization is using the Darwin Information Typing Architecture (DITA) to pilot XML-based structured authoring and advanced content management. Background Solution selling presents special challenges to our Information Development organization. In particular, our traditional infrastructure does not accommodate reassembling content to support the variety of product combinations that BSM solutions require. The need for us to customize BSM solutions by integrating different software solutions, combined with the maturation of tools for XML-based authoring, make this an ideal time to implement a new information development strategy. After researching materials about content management and studying success stories from companies who have implemented structured authoring, we launched a pilot project with the following goals: Develop a new information architecture and infrastructure to support integrated solutions Improve the quality of our deliverables Make information development more efficient Reduce localization costs Issues We determined that our new architecture and infrastructure would need to meet the following requirements: Scalable across departments and content types Customizable across products and functions Non proprietary architecture Robust enough to meet complex functional requirements Affordable Maintainable, given our available resources What we did and why We chose to limit the content set for the pilot to accommodate developing an end-to-end solution in a reasonable amount of time. This article discusses the analysis and design phases of the project as they relate to the information architecture, entailing two primary tasks: Developing information models or "blueprints" for our new information architecture Developing the corresponding XML models to implement the information architecture Developing information models After a thorough content audit and analysis, we developed information models for two types of content: system messages and installation. We created Excel spreadsheets to represent the models, which documented the structure of each required component, without regard to technology. For example, the messages model has a component called message module, which defines the structure and necessary elements for documenting an individual system message. Developing XML models with DITA To develop the XML models, we adopted DITA as our starting architecture. Why DITA? We can customize DITA to meet our needs. The DITA toolkit offers a head start in developing DTDs and transforms. DITA takes full advantage of XML by focusing on modularity. By steering writers toward a component-based authoring paradigm, DITA promotes reuse and consistency in content and structure. The DITA community encourages rapid growth of technology through exchange of ideas and techniques. We joined the OASIS DITA Technical Committee to stay informed of changes, learn from other members, and influence further development of the DITA specification. To date, we have completed the XML models for one information type (system messages) and are working on the second type (installation). In addition to converting 1,000 pages of content to the new XML architecture, we developed a working prototype that demonstrates the following features of our new strategy: Generating multiple deliverables from a single source through conditional processing (based on DITA maps) Generating a deliverable in multiple output formats Reassembling and integrating content by modifying DITA maps Changing common content once and proliferating the change to all affected deliverables Upcoming challenges We continue to face challenges as project development proceeds. Limited resources prevent us from moving as quickly as we would like. Given our substantial volume of information, implementing the new strategy across the company will require significant investments of time and effort. Also, any transition strategy must accommodate our classic products plus new standards from acquired companies and partners-another significant hurdle. We also face a number of technical challenges. While DITA provides a solid base, we still need to "make it fit" our BMC Software information models, meaning we have to develop numerous specializations for each information type. Finally, particular DITA limitations present challenges for us. In the current toolkit, we cannot create custom attributes. (DITA developers plan to address this limitation in the future.) Also, we need an indexing solution; the current toolkit does not provide the support that we need. Nonetheless, the advantages of DITA clearly outweigh the limitations. Attainable benefits Based on our efforts to date, we believe that we can achieve the following benefits by implementing DITA-based information architecture at BMC Software: Create integrated content to support any combination of products Reduce shipment sizes, simplifying users' experiences Develop advanced content, which customers are demanding Ensure that content is accurate and presented consistently Reduce localization costs Streamline information development The pilot's outcome The pilot's outcome is yet to be determined. On track to complete the pilot this year, we have finished information modeling and half of the XML modeling. Also, we are in the process of converting additional content to XML based on the new architecture. What have we learned so far? We can summarize our key lessons as follows: Completing a thorough content audit before developing the information model is critical. Auditing the content ensures that the model will suit many different products. Information modeling takes an iterative approach and, thus, requires a significant amount of time. Factoring sufficient time into the project plan is essential. Information modeling should focus solely on content, independent of technology. DITA is a solid architecture that offers a great head start, but it takes significant effort to make DITA work for a specific implementation. An Interview with Wendy Shepperd Why did you choose to implement in DITA? There was a lot of background research in the company that went on before the project started. We came to a consensus that DITA had what we needed to implement our XML models. That fact that it had been turned over to OASIS helped to convince us that DITA was well on its way to becoming a standard. The key was that we would not have to start from scratch and would be able to leverage the knowledge of the DITA team. It was available, public, and a good head start. It is a pretty impressive architecture. We are really impressed with the architecture and how it's working. Did you look at other models/standards other than DITA? There are a number of people in house who had an SGML background and knowledge of DocBook. We also had good understanding of XML and considered building XML DTDs from scratch. We considered everything that we felt was available and selected DITA. DocBook is robust, mature and an architecture worth considering, but is geared to printed books, as well as being more complex than they needed. We also felt that DITA was more flexible. How did you map your models against DITA? What is the relationship between the two?" We built the models without regard to technology, our goal being to determine the information objects. We also had a parallel project to learn DITA, understand the capabilities of DITA, and determine how we could implement it. Then we mapped our models to DITA, using all of the base structures in DITA we could, and then added the specializations that we needed for the content elements we identified as being missing in DITA. We made a conscious decision not to extend DITA unless we absolutely had to. Where transforms are concerned, we used the entire set of DITA. For authoring, we used a subset of DITA. Pieces we didn't need, we hid from authors. How will you work around the limitations you've identified? For the pilot we are just going to use what DITA provides. There are some work arounds offered by the DITA developers but we have decided that the attributes that DITA provides will be sufficient for the pilot. The next version of DITA should have some extensions to better fit our needs. We currently don't have a work around for indexing. We are researching options, but have not figured out how to deal with this yet. What has been the most difficult part of the project to date? One of the most difficult parts has been learning how to model the information and then learning how to write the specializations in DITA to map the model. Learning has been the trickiest because we had to learn both modeling and how to code the model. Like any project, just getting the processes down for writing the DITA specializations and validating them against the model was difficult. We tried different approaches, a couple of iterations with input from Dan Day and Michael Priestly. There were things that we just didn't know about DITA that we had to figure out or that people had to tell us about. Also, there is no dedicated team. And it takes a lot of time to code up all this stuff and to test it. Have the writers shown any reservations about the modular approach? The entire pilot team is behind the project. The change management issues will come later in the project. Change management is very important. We are trying to be as transparent as possible, so that we can communicate as much as we possibly can to other groups. We have also had some challenges keeping the models and the implementation in sync as we start plugging in the content. When you plug in the content you are testing the model and you must revisit the model to accommodate how it evolves over time. Do you foresee any specific change management issues? All the usual suspects. This is a paradigm shift from the way we author today. We currently author in a traditional method of writing books, where a writer owns the book from beginning to end. Now we are moving to a more collaborative environment, where authors provide models. That's probably one of the biggest challenges in changing processes in an organization. With any change management process, you have the continuum from early adopters to resisters. We see getting everybody in step as one of the biggest challenges. So, we've tried to get as many people involved in the pilot as we can, and to communicate as much as we can, while remembering that this is a pilot project. Authors using DITA in the pilot have shown us that they are comfortable with DITA and the authoring environment. The tools have the ability to hide or show as much tagging as possible. Authors can see what they want to see. Pilot authors have been able to get up and running very quickly. The authors will not need to really know DITA and XML. The real issue is learning how to write in a structured scheme for reuse.