DITA and the death of technical documentation as we know it

In this introductory article, Andrew J. Thomas argues for shifting product and system design documentation development to new approaches such as the Darwin Information Typing Architecture (DITA) to support the growing use of Agile techniques to deliver reliable systems based on increasingly complex hardware and software designs.

Companies today are facing incredible challenges to deliver products to market at increasingly faster speeds, while simultaneously improving quality and performance.

Many have moved to Agile development processes to streamline the work involved in bringing a product to market. However, customers still expect the same high quality releases they have grown accustomed to, including accurate, and in some cases localized, technical documentation.

Further, many customers actually expect more product information to be available to them, sometimes even before purchasing the product. For these reasons, traditional technical documentation as we know it is slowly dying, as it no longer meets the needs of companies or their customers.

For some, this death is occurring as many move away from documentation towards knowledgebase articles, uncontrolled wikis, simplistic videos, or worse still, no documentation at all. But there is a better approach. Technical documentation can actually fill this void by transforming into intelligent product content. Many companies are turning to structured content, and the Darwin Information Typing Architecture (DITA) specifically, to achieve this and alleviate internal and external pressures.

When combined with the right technology to automate the management and publishing of this content, the result is product content that is both intelligent and interactive, allowing companies to meet changing customer needs while controlling costs and streamlining processes.

A short history of technical documentation

Several years ago, many software companies began to realize that their traditional documentation and publishing methodologies were not keeping pace with emerging delivery mediums, such as the Web. With the explosion of mobile phones, it became increasingly obvious that a better solution was needed for content distribution.

These companies, often willing to invest in emerging technology before other businesses, determined that XML was the key to transforming their technical documentation. By separating form, the structure and delivery of the content, from function, the purpose of the content, they were able to centralize and re-use product content across a wide array of deliverables while automating the publishing process.

It is worth noting, however that most of these early solutions were developed completely in house, and at great expense and even costlier maintenance. Additionally, these home grown tools did not align with the new Agile methodologies taking place in Engineering.

In 2005 OASIS ratified DITA XML as an open standard. Originally developed by IBM, DITA  defines an XML architecture for designing, writing, managing, and publishing information.

With the advent of DITA, companies now have a standard approach for structuring technical documentation into modular, stand alone topics. This componentized version of documentation dovetails with Agile development practices quite nicely.

Topics can be identified for completion within sprints, while automated publishing output can be integrated into automated build processes. Putting this into practice are companies such as HP, EMC, Cisco and others who are changing how they develop and deliver technical information to their customers.

This shift to structured content is as massive as the revolution that overtook marketing departments with the emergence of the company website. In the beginning, static HTML suited marketing needs, but as the website became a critical business tool and essential to the customer relationship, sites became complex, dynamic and interactive, necessitating a constant change to the content. These same drivers are now affecting technical documentation.

Many companies are wondering how DITA might help them transform their entire business processes to engage customers more directly with personalized and relevant product content that greatly enhances their customers’ experience with their company. This transformation does not happen overnight, and the journey needs to be defined so companies can identify where they are today, where they want to go, and how they can get there.