DITA and the death of technical documentation as we know it - Embedded.com

DITA and the death of technical documentation as we know it

I n 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.

The Product Content Maturity Model
SDL has been involved with DITA from its earliest stages, participating on the OASIS standards committee and helping many of today’s technology leaders integrate DITA into their processes and infrastructure.

By working with companies that started the journey to transform technical documentation into product content, we’ve witnessed the various stages they’ve gone through in maturing their processes. We also see hints of future stages that many are actively working to achieve. We find that this journey takes place in five stages of increasing maturity (Figure 1 below ).

Figure 1. Five stages of documentation maturity

Stage 1: Aware
When companies realize the old book paradigm is no longer meeting customer needs or scaling with business growth, they rapidly arrive at the first stage of the product content maturity model: Aware.

The beginning of any significant change within an organization starts with awareness and shifting cultural values as a result of that awareness. It often starts within the technical documentation team struggling to meet the demands being made of them.

Perhaps customers are having a hard time finding the right information in existing documentation and customer support calls are escalating as a result. Or maybe these customers expect content available on their smart phones and tablet devices, pre-filtered to only show the content they’re most interested in.

Many times the demand is simply a top down decree to cut operating budgets while expecting the deliverables be maintained or increased. For agile developers, the demand is for faster turnaround times that match up with the engineering iterations. However the organization arrives at the first stage, it invariably involves changing the old process to meet these new demands.

At this time companies should become better educated about DITA, and begin to organize their unstructured content with an eye toward re-use. In preparation for migrating to structure, content creators should develop corporate style guides that emphasize minimalism and consistent terminology that is applicable to all the content creation groups responsible for generating product content.

It is crucial that this terminology exercise span all the groups responsible because that begins the foundation for later transformations throughout the company.

Stage 2: Structured
Now that the company has become aware of the problems inherent in unstructured, static content, the solution becomes obvious: structured, modular content. DITA is the obvious choice for most product companies because it allows the content to be broken down into more re-usable pieces that can be shared, rearranged, and conditioned to deliver a much broader range of deliverables in any number of formats.

DITA begins with standalone topics that fall into three major categories out of the box: concepts, references, and tasks. Because the topics are written to be read independently from one another, these topics can be arranged in any order for any number of publications. These arrangements are stored in DITA maps, but a single topic can be referenced by numerous maps.

Additionally, for each publication, conditions can determine which content is pulled into the publication, in an order based on the maps, with the appropriate formatting applied for the desired output. Because the content is stored as XML, any format can be supported.

This approach provides the flexibility companies need, however, embracing structure is not without its own challenges. Content creators must learn a very different way of creating content that involves new tools and technology.

Additionally, the explosion of individual topics quickly becomes too cumbersome for most writing groups to manage manually on a file system. Finally, a significant leap like this is often met with some internal resistance.

Change is always disruptive, but if you demonstrate the value that structure brings, and how the organization can dramatically improve customer experience, acceptance is more likely. With acceptance, technical communication teams can expand usage of structured content to include subject matter experts and eventually other departments throughout the company.

At this stage, the company will have invested in some amount of technology to facilitate the initial migration from unstructured content to DITA. Typically this involves desktop authoring tools specialized for XML, automated publishing tools, and a component content management system.

Once the organization becomes familiar with DITA, managing publications becomes easier and new combinations of deliverables can be created. Additionally, older processes for maintaining and enriching content can be reevaluated for process improvements.

Component content management systems take care of versioning, but structured content often frightens team members responsible for review and casual content contribution.

Content creation teams should investigate new roles that emerge when creating structured content such as information architects and shared content editors. Solid processes should be developed for the creation and maintenance of shared content.

Re-use is one of the quickest and most powerful advantages of DITA but it must be managed effectively for maximum efficiency. If content is shared across teams, regular communication should be implemented to maintain a standard creative approach.

Stage 3: Collaborative
Once existing technical documentation has moved to DITA, the next step is to involve all contributors in the content creation process. In the past, collaboration involved face to face meetings where printed documents would be marked up manually. Communication was very efficient but content updates were slow and time consuming.

With the IT revolution, businesses became more globally distributed and teams no longer worked in the same location. Collaboration suffered as a result and meetings moved to long phone calls, chaotic email chains, and content review was managed haphazardly with little to no version control. However the review process was easy for casual content contributors and subject matter experts.

Better tools are available today to enable global communication, but managing the collaborative process is still cumbersome. By moving to DITA, content creators benefit from re-use and easier localization, but often remain stuck in older review processes with PDF files or copy and paste into Word or email.

Unfortunately this process is time consuming, manually intensive and error prone. However, subject matter experts are familiar with these simple editing interfaces and don’t have the time or proficiency to learn advanced technical writing tools just to contribute their thoughts and comments about the product content.

For example, many engineering teams find it easier to update an internal wiki with their specifications or review comments. This information has to then be copied into the structured content, eroding the original efficiency gains of DITA.

Therefore, it is crucial that the company deploy easy to use content creation and review tools that maintain the structure for these subject matter experts while simultaneously providing easy preview mechanisms of the content in all of the variations it might be published.

Team members should continue to meet using existing communication tools, but strive to implement comments, edits, and content contributions within tools that maintain structure. This enables consistent re-use and drives efficiency by eliminating repeated content entry.

Centralized terminology and style guides should be well integrated with the creation process, regardless of who is creating the content, ensuring a consistent voice. Allowing subject matter experts to not only review content, but to contribute new content also can dramatically improve the company’s product content.

Tech writers can now focus on conditioning content for greater re-use and standardizing product content categories. Additionally, technical toolsmiths who are frequently responsible for maintaining home grown publishing solutions can now spend more time on newly emerging media, such as social networks and mobile channels to prepare for increased customer engagement.

STAGE 4: Transformative
With all content creators, subject matter experts, and casual contributors involved in a now-standard process, the company begins to leverage structured product content throughout the organization. This is the point at which technical documentation has ceased to exist within the organization.

It’s transformed into product content by the very acknowledgement by the company that all customer-facing content impacts brand and the customer experience. Organizational divisions become less relevant when creating new product content. A cultural value emerges around collaborative sharing and siloed approaches are frowned upon. The focus revolves around the content and how it can help the user and less about who creates or maintains it (Figure 2, below.

Figure 2. XML forces a focus on content and the user
As an example, product content may begin as a user story within an engineering sprint, written first by the product owner, refined by the sprint team, and eventually turned into a standalone DITA topic. As a topic, it now can be repurposed by the training team, copied into a support knowledgebase, and shared with partners.

Depending on the content, it might even become the basis for marketing materials. By using structure however, companies can maintain all of these variations within the topic, in a single XML repository, ensuring proper versioning and consistency across all the deliverables that reference it.

To facilitate this vision, companies should allow ad-hoc content creation teams to form as needed, so long as standard processes are followed and content structure is maintained.

In preparation for the final phase, companies should develop customer profiles by working with all departments responsible for product content. Then focus content creators and information architects to apply those customer profiles to all product content, ensuring that deliverables are more targeted.

Stage 5: Engaging
The final stage is yet to be achieved by most companies today, even if they’ve invested in structured content and DITA for many years. However, by transforming technical documentation into intelligent product content, the company is well positioned to engage customers more directly and appropriately.

Product content has evolved over the years and with the Web, has begun reaching greater numbers of customers than ever before. Content, more than products, often has the power to establish and maintain customer relationships.

Many marketing and support organizations probably already have customer engagement programs in place, but these efforts are limited to their department in scope. Until a company goes through the transformative stage of product content maturity, engagement remains as siloed as content creation.

However, these groups in particular already understand that customer engagement is a continuous process. At this stage of maturity, the company moves beyond simply publishing product content once, but rather to a continuous flow of creation, review, publication, and update based on direct customer feedback.

Additionally, while specific deliverables may continue to be maintained, increasingly the company will allow the customer to dictate the content they wish to consume, in the format they want to consume it in.

By re-using a large amount of product content across the company, more time can be spent on customer profiles that color the content appropriately for specific audiences.

This personalized approach to product content helps the customer find the right answers and improves their experience with the company. Content creators can engage directly with customers through feedback loops and direct conversations.

Marketing can also leverage content utility analytics to determine which topics are most valuable to customers and target their campaigns accordingly. Support can track customer search history to detect potential problems before they escalate to their call centers.

In conclusion, technical documentation is reaching the end of its life cycle and companies must transform their documentation into engaging product content in order to compete in today’s competitive world.

Doing so allows a company to dynamically deliver product content on demand, created and filtered for customer profiles. It can be maintained with incremental updates without sacrificing standard version control. Branding and terminology is maintained, regardless of who creates the content and re-use is possible at every creation point, ensuring consistency.

A social interaction between the community of content consumers and authors is facilitated and the crowd can even engage in contributing their own content. Analytics are captured and reported within the company to continually improve product content utility for the customer.

The product content maturity model defines the series of steps companies can take in this transformation. Many companies have started the journey already.

And while this journey can require significant time and effort with increasing maturity along the way, each stage offers measurable benefits to the organization that is working with structured content.

It also provides a common framework for collaboration and best practices across multiple departments and disciplines. The end result provides the greatest opportunity for superior customer engagement by allowing a company to interact more fully and appropriately with their customers.

References for further information

1 – Introduction to the OASIS DITA specification
2 – IBM on the Darwin Information Typing Architecture
3 – What is DITA?
4 – Comprehensive list of DITA resources

Andrew Thomas is the Director of Product Marketing for Structured Content Technologies at SDL International. He has worked in the localization industry for more than a decade, managing the translations of a wide variety of content, from computer games to printed manuals to web applications. Before joining SDL, he was a language intelligence solutions manager for Adobe Systems and oversaw the translation process for their DITA content.

This article provided courtesy of Embedded.com and EmbeddedSystems Design Magazine. Sign up for subscriptionsand newsletters. Copyright © 2011 UBM–All rights reserved.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.